Mac Messages MCP

Uma ponte em Python para interagir com o aplicativo Mensagens do macOS.

Documentação

Mac Messages MCP

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app.

Mac Messages MCP roda localmente no seu Mac. Ele abre os bancos de dados de Mensagens e Contatos em modo somente leitura, retorna apenas os dados que um cliente solicita e usa a automação do Messages.app somente quando o cliente chama explicitamente a ferramenta de envio.

[!IMPORTANT] Este servidor é exclusivo para macOS. Ler mensagens requer Acesso Total ao Disco. Enviar requer um Mac conectado ao Messages, além de permissão para o aplicativo de lançamento automatizar o Messages.

O que ele pode fazer

Ler mensagens recentes em todas as conversas ou filtrar por contato ou conversa em grupo
Pesquisar texto de mensagens com correspondência aproximada em um intervalo de tempo, incluindo todo o histórico disponível
Encontrar contatos por nome aproximado e retornar números de telefone prontos para envio
Listar conversas em grupo nomeadas e usar seus IDs de conversa para leituras ou envios
Enviar iMessage, com fallback para SMS/RCS para destinatários de telefone elegíveis
Verificar se um destinatário parece acessível via iMessage antes de enviar
Encontrar anexos por data, remetente e tipo MIME
Retornar imagens pequenas inline, converter imagens HEIC para PNG ou retornar um caminho local para arquivos maiores e não-imagem
Diagnosticar permissões dos bancos de dados de Mensagens e Contatos de dentro do cliente MCP

Início rápido

1. Instalar `uv`

brew install uv

Confirme que o lançador está disponível:

uvx --version

Python 3.10 ou mais recente é necessário. uvx pode provisionar um Python compatível e instala o Mac Messages MCP em um ambiente isolado, então você não precisa criar um ambiente virtual primeiro.

2. Conceder permissões do macOS

Abra Ajustes do Sistema → Privacidade e Segurança → Acesso Total ao Disco e ative o aplicativo que lançará o servidor MCP:

Claude Desktop, Cursor, VS Code ou o aplicativo de desktop do ChatGPT quando configurado nesse aplicativo
Terminal, iTerm2, Ghostty ou outro terminal ao usar Claude Code ou Codex CLI a partir desse terminal

Saia e reabra o aplicativo após alterar o Acesso Total ao Disco. No primeiro contato ou envio, o macOS pode pedir separadamente acesso aos Contatos ou permissão para controlar o Messages. Permita esses avisos.

Também certifique-se de que o Messages.app esteja aberto, conectado e já capaz de enviar uma mensagem normal.

3. Adicionar o servidor ao seu cliente MCP

O comando do servidor é o mesmo em todos os lugares:

uvx mac-messages-mcp

Escolha seu cliente abaixo.

Claude Desktop

Abra Claude → Configurações → Desenvolvedor → Editar Configuração e adicione:

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

Preserve quaisquer outros servidores já presentes em claude_desktop_config.json, salve o arquivo e reinicie o Claude Desktop.

O Claude Desktop também suporta extensões instaláveis do .mcpb. Veja Criar a extensão do Claude Desktop se quiser empacotar este repositório como uma.

Claude Code

Adicione uma vez no escopo do usuário para que fique disponível em todos os projetos:

claude mcp add --transport stdio --scope user mac-messages -- uvx mac-messages-mcp

Verifique:

claude mcp get mac-messages

Dentro do Claude Code, execute /mcp para inspecionar a conexão e as ferramentas.

Codex CLI, extensão IDE do Codex e aplicativo de desktop do ChatGPT

Clientes Codex no mesmo Mac compartilham a configuração do MCP. Adicione o servidor com:

codex mcp add mac-messages -- uvx mac-messages-mcp

Depois verifique:

codex mcp list

Você também pode adicioná-lo diretamente a ~/.codex/config.toml:

[mcp_servers.mac-messages]
command = "uvx"
args = ["mac-messages-mcp"]

Reinicie o aplicativo de desktop ou a extensão do IDE após alterar a configuração. No Codex CLI, use /mcp para visualizar o servidor ativo.

Cursor

Ou abra Cursor Settings → Tools & MCP → New MCP Server e use:

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

Reinicie o servidor nas configurações de MCP do Cursor após salvar.

VS Code / GitHub Copilot

Abra a Paleta de Comandos e execute MCP: Add Server. Escolha Command (stdio), digite uvx como comando, adicione mac-messages-mcp como argumento e instale globalmente.

Ou adicione a partir de um terminal:

code --add-mcp '{"name":"mac-messages","command":"uvx","args":["mac-messages-mcp"]}'

A entrada equivalente de mcp.json no nível de usuário ou espaço de trabalho é:

{
  "servers": {
    "mac-messages": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mac-messages-mcp"]
    }
  }
}

[!NOTE] O VS Code usa um objeto servers de nível superior. Claude Desktop e Cursor usam mcpServers.

Outros clientes MCP stdio

Use esta definição genérica de servidor:

{
  "command": "uvx",
  "args": ["mac-messages-mcp"]
}

Se um cliente GUI relatar que uvx não pode ser encontrado, execute which uvx no Terminal e substitua "uvx" pelo caminho absoluto retornado. O Homebrew normalmente o instala em /opt/homebrew/bin/uvx em Apple silicon e /usr/local/bin/uvx em Macs Intel.

4. Verificar a conexão

Peça ao seu cliente para chamar tool_check_db_access e depois tool_check_addressbook. Quando ambos tiverem sucesso, tente comandos como:

Show me my messages from the last two hours.

Find messages from Carter about dinner in the last 30 days.

Find PDFs sent to me this month, but do not open any yet.

Find Jordan in my contacts and draft a message saying I am running 10 minutes
late. Do not send it until I confirm.

O primeiro lançamento do uvx pode demorar mais enquanto baixa e armazena em cache as dependências do Python.

5. Opcional: definir a região do número de telefone

Números de telefone escritos em formato nacional (06 39 98 00 01, (415) 555-1234) precisam ser expandidos para E.164 antes de poderem ser correspondidos com o banco de dados de Mensagens, e essa expansão precisa saber a qual país eles pertencem. O servidor lê a configuração de região do seu próprio Mac para isso, então em um Mac configurado corretamente não há nada a fazer.

Defina MAC_MESSAGES_REGION para um código ISO 3166-1 alpha-2 quando seus números pertencerem a uma região diferente daquela em que seu Mac está configurado — um SIM francês em um Mac configurado para en_US, por exemplo:

{
  "mcpServers": {
    "mac-messages": {
      "command": "uvx",
      "args": ["mac-messages-mcp"],
      "env": { "MAC_MESSAGES_REGION": "FR" }
    }
  }
}

Para Claude Code:

claude mcp add --transport stdio --scope user \
  --env MAC_MESSAGES_REGION=FR \
  mac-messages -- uvx mac-messages-mcp

A região é resolvida uma vez na inicialização, então reinicie o servidor após alterá-la. Ordem de resolução: MAC_MESSAGES_REGION, depois a preferência AppleLocale do macOS, depois LC_ALL / LC_CTYPE / LANG, depois US. Números já escritos em E.164 (+33639980001) nunca são reinterpretados e não precisam de nada disso.

Ferramentas disponíveis

Ferramenta	Finalidade	Efeito colateral
`tool_get_recent_messages`	Ler mensagens recentes, opcionalmente filtradas por contato ou ID de conversa em grupo	Somente leitura
`tool_fuzzy_search_messages`	Pesquisar corpos de mensagens por correspondência aproximada de texto; padrão de 30 dias, ou use `hours=0` para todo o histórico	Somente leitura
`tool_find_contact`	Corresponder aproximadamente um nome em Contatos e retornar números de telefone	Somente leitura
`tool_get_chats`	Listar conversas em grupo nomeadas e seus identificadores	Somente leitura
`tool_search_attachments`	Encontrar metadados de anexos por data, contato, tipo MIME e limite	Somente leitura
`tool_get_attachment`	Buscar um anexo por ID, inline quando suportado ou como caminho local	Somente leitura
`tool_check_imessage_availability`	Verificar disponibilidade provável de iMessage para um número de telefone ou e-mail	Somente leitura
`tool_check_db_access`	Diagnosticar acesso a `~/Library/Messages/chat.db`	Somente leitura
`tool_check_contacts`	Retornar uma contagem de contatos e uma pequena amostra	Somente leitura
`tool_check_addressbook`	Diagnosticar acesso ao banco de dados de Contatos/AddressBook	Somente leitura
`tool_send_message`	Enviar uma mensagem direta ou em grupo pelo Messages.app	Envia uma mensagem real

O servidor também expõe dois recursos MCP:

messages://recent/{hours}
messages://contact/{contact}/{hours}

Trabalhando com contatos, conversas e anexos

Destinatários

Para mensagens diretas, números de telefone E.164 são o formato mais confiável:

+14155551234

Números escritos em formato nacional também funcionam. Eles são expandidos para E.164 usando a região em que seu Mac está configurado, então (415) 555-1234 torna-se +14155551234 em um Mac dos EUA e 06 39 98 00 01 torna-se +33639980001 em um francês. Defina MAC_MESSAGES_REGION para um código ISO 3166-1 alpha-2 (MAC_MESSAGES_REGION=GB) quando seus números pertencerem a uma região diferente da do seu Mac. Números já em E.164 nunca são reinterpretados.

O servidor também aceita endereços de e-mail, nomes de contatos e seleções de contact:N retornadas após uma busca de contato ambígua.

Para uma conversa em grupo, chame tool_get_chats, passe seu ID de conversa para tool_send_message e defina group_chat=true. Use o mesmo ID como chat_id em tool_get_recent_messages para ler essa conversa.

Anexos

O acesso a anexos é deliberadamente dividido em três etapas:

Leituras e buscas de mensagens adicionam marcadores compactos como [attachments: #42 image/jpeg (invitation.jpg)].
tool_search_attachments pesquisa metadados sem carregar o conteúdo dos arquivos.
tool_get_attachment busca um anexo selecionado.

Imagens de até 5 MB são retornadas inline por padrão. Imagens HEIC são convertidas para PNG. Imagens maiores, PDFs, vídeo e áudio são retornados como caminhos locais do sistema de arquivos para que o cliente MCP decida se deseja abri-los. Adesivos, cargas de pré-visualização de links e contêineres .pluginPayloadAttachment são filtrados.

Privacidade e segurança

Conexões SQLite de Mensagens e Contatos usam modo somente leitura e query_only do SQLite.
O servidor não envia, espelha, indexa ou mantém seu próprio arquivo de mensagens.
Os resultados são gravados na conexão local MCP stdio iniciada pelo seu cliente.
A saída de ferramentas e recursos derivada de Mensagens/Contatos é estruturalmente neutralizada (quebras de linha incorporadas e controles ASCII não podem formar linhas extras de transcrição; caracteres invisíveis, de formato e bidirecionais são mostrados como escapes) e retornada dentro de um bloco <untrusted-mcp-output> explícito. Isso não é uma garantia anti-injeção: conteúdo de terceiros de iMessage/SMS ainda pode tentar injeção de prompt. O servidor torna esse conteúdo não estrutural e rotulado; o cliente não deve tratá-lo como autorização, confirmação ou instruções de ferramenta.
Bytes de anexos são retornados somente após uma busca explícita e têm limite de tamanho para imagens inline. Nome de arquivo, MIME, caminho e outros metadados de texto são neutralizados com o mesmo limite; cargas de imagem são preservadas.
O envio é isolado em tool_send_message, escapa entradas do AppleScript e usa um tempo limite de execução limitado. Este servidor não realiza confirmação humana; o cliente MCP deve controlar os envios.
Acesso Total ao Disco é mais amplo que o acesso ao Messages. Conceda-o apenas a clientes MCP em que você confia e revise o destino antes de aprovar um envio.

Veja SECURITY.md para relatar uma vulnerabilidade em particular.

Solução de problemas

`uvx` ou `spawn uvx ENOENT`

O aplicativo GUI não consegue ver o caminho do Homebrew do seu shell. Execute:

which uvx

Use esse caminho completo como o command do MCP e reinicie o cliente.

`Operation not permitted`, `unable to open database file` ou nenhuma mensagem

Conceda Acesso Total ao Disco ao aplicativo que lança o servidor, não apenas ao Messages.app. Saia completamente e reabra o lançador depois, e então chame tool_check_db_access novamente.

Para Claude Code ou Codex CLI, o lançador normalmente é seu terminal. Para uma integração de desktop ou IDE, normalmente é o próprio Claude Desktop, Cursor, VS Code ou o aplicativo de desktop do ChatGPT.

Contatos vazios ou falha na busca de contatos

Permita que o aplicativo de lançamento acesse os Contatos se o macOS solicitar. Confirme o Acesso Total ao Disco, reinicie o aplicativo e chame tool_check_addressbook seguido de tool_check_contacts. Se os contatos estiverem listados, mas seus números tiverem o código de país errado, o servidor está expandindo seus números no formato nacional contra a região errada. Defina MAC_MESSAGES_REGION para o código ISO 3166-1 alpha-2 correto e reinicie o servidor.

A leitura funciona, mas o envio falha

Abra o Messages.app e envie uma mensagem manualmente para confirmar que a conta e o destinatário funcionam.
Verifique System Settings → Privacy & Security → Automation e permita que o aplicativo de inicialização controle o Messages.
Prefira um número E.164 como +14155551234 para um destinatário direto.
Use tool_check_imessage_availability para inspecionar a rota provável.

Um anexo está listado, mas não pode ser aberto

O Messages pode reter metadados do banco de dados após o macOS ter descarregado o arquivo. Abra a conversa no Messages.app e baixe o anexo, depois tente novamente tool_get_attachment.

O servidor parece travar quando executado no Terminal

Isso é normal para um servidor MCP stdio: ele aguarda entrada de protocolo de um cliente. Use a visualização de status MCP do seu cliente ou inicie o MCP Inspector:

yarn dlx @modelcontextprotocol/inspector uvx mac-messages-mcp

Instalar como ferramenta autônoma

Clientes MCP podem iniciar o pacote diretamente com uvx; uma instalação permanente é opcional.

uv tool install mac-messages-mcp
mac-messages-mcp

Atualize ou remova-o com:

uv tool upgrade mac-messages-mcp
uv tool uninstall mac-messages-mcp

API Python

O servidor MCP é a interface principal, mas o pacote também exporta suas funções principais de leitura/envio:

from mac_messages_mcp import get_recent_messages, send_message

recent = get_recent_messages(hours=48)
print(recent)

result = send_message(
    recipient="+14155551234",
    message="Hello from Mac Messages MCP!",
)
print(result)

Essas chamadas usam as mesmas permissões do macOS e podem enviar mensagens reais.

Desenvolvimento

git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

uv sync --frozen --extra dev
uv run pytest
uv run black --check .
uv run isort --check-only .
uv build

Os testes simulam AppleScript e usam fixtures temporárias de banco de dados; eles nunca devem ler dados reais de Messages ou Contatos de um colaborador. Consulte CONTRIBUTING.md para a lista de verificação de contribuição e VERSIONING.md para lançamentos.

Construir a extensão Claude Desktop

O repositório inclui um MCPB manifest.json e um script de build que pode agrupar um binário uv específico de arquitetura:

yarn global add @anthropic-ai/mcpb
uv run python scripts/build_mcpb.py

Para um build Intel:

uv run python scripts/build_mcpb.py --arch x86_64

Instale o .mcpb gerado em Claude Desktop → Settings → Extensions → Advanced settings → Install Extension…. Uma extensão agrupada ainda precisa de acesso à rede no primeiro lançamento para baixar Python e as dependências do pacote.

Use --no-bundle para empacotar contra o uv do sistema, ou execute uv run python scripts/build_mcpb.py --help para todas as opções.

Docker

O Dockerfile incluído é para validação de pacote e catálogo. Um contêiner Linux não pode acessar as permissões TCC do macOS ou automatizar o Messages.app, então o Docker não é uma forma suportada de ler ou enviar mensagens no Mac host.

Licença

Contribuindo

Issues e pull requests focados são bem-vindos. Não inclua conteúdos reais de mensagens, contatos, números de telefone, arquivos de banco de dados ou anexos em relatórios de bugs ou fixtures.

Changelog · Contribuindo · Segurança · PyPI

Mac Messages MCP

Documentação

Mac Messages MCP

O que ele pode fazer

Início rápido

1. Instalar uv

2. Conceder permissões do macOS

3. Adicionar o servidor ao seu cliente MCP

Claude Desktop

Claude Code

Codex CLI, extensão IDE do Codex e aplicativo de desktop do ChatGPT

Cursor

VS Code / GitHub Copilot

Outros clientes MCP stdio

4. Verificar a conexão

5. Opcional: definir a região do número de telefone

Ferramentas disponíveis

Trabalhando com contatos, conversas e anexos

Destinatários

Anexos

Privacidade e segurança

Solução de problemas

uvx ou spawn uvx ENOENT

Operation not permitted, unable to open database file ou nenhuma mensagem

Contatos vazios ou falha na busca de contatos

A leitura funciona, mas o envio falha

Um anexo está listado, mas não pode ser aberto

O servidor parece travar quando executado no Terminal

Instalar como ferramenta autônoma

API Python

Desenvolvimento

Construir a extensão Claude Desktop

Docker

Licença

Contribuindo

1. Instalar `uv`

`uvx` ou `spawn uvx ENOENT`

`Operation not permitted`, `unable to open database file` ou nenhuma mensagem