mcp-meta

MCP server para Meta Business Messaging: WhatsApp Cloud API, Messenger Platform, Instagram Messaging e Graph API Webhooks.

Cobre ~55 tools agrupadas em 4 produtos. Todos os endpoints apontam para graph.facebook.com/{version} (default v22.0, override via META_API_VERSION).

Instalação

cd /Users/barboza/Solutions/mcp-meta
npm install
npm run build

Configuração (variáveis de ambiente)

Todas são opcionais — também podem ser passadas por chamada via access_token / phone_number_id / etc. nos args do tool. Env apenas serve como default.

Env	Uso
META_API_VERSION	Versão da Graph API (default v22.0)
META_BASE_URL	Base URL (default https://graph.facebook.com)
META_APP_SECRET	Usado por webhook_validate_signature
META_VERIFY_TOKEN	Token de handshake (hub.verify_token)
WHATSAPP_ACCESS_TOKEN	Bearer para Cloud API
WHATSAPP_PHONE_NUMBER_ID	ID padrão do número emissor
WHATSAPP_BUSINESS_ACCOUNT_ID	WABA ID (templates, phone numbers)
MESSENGER_PAGE_ACCESS_TOKEN	Token da Page FB
MESSENGER_PAGE_ID	ID da Page padrão
INSTAGRAM_PAGE_ACCESS_TOKEN	Token da Page ligada ao IG (default: mesmo MESSENGER_PAGE_ACCESS_TOKEN)
INSTAGRAM_USER_ID	IG user ID, se aplicável

Uso via Claude Code / MCP client

Adicione em ~/.claude.json (ou equivalente):

{
  "mcpServers": {
    "meta": {
      "command": "node",
      "args": ["/Users/barboza/Solutions/mcp-meta/dist/index.js"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "EAAJB...",
        "WHATSAPP_PHONE_NUMBER_ID": "1234567890",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "987654321",
        "MESSENGER_PAGE_ACCESS_TOKEN": "EAAJB...",
        "MESSENGER_PAGE_ID": "1111111",
        "META_APP_SECRET": "...",
        "META_VERIFY_TOKEN": "..."
      }
    }
  }
}

Para desenvolvimento (tsx, sem build):

"args": ["--import", "tsx", "/Users/barboza/Solutions/mcp-meta/src/index.ts"]

Tools disponíveis

Descoberta

• meta_list_tools(product?) — lista todas as ferramentas e endpoints mapeados
• Resource meta://reference/endpoints.json — catálogo completo em JSON

WhatsApp Cloud API (~26 tools)

Mensagens: whatsapp_send_text, whatsapp_send_image, whatsapp_send_audio, whatsapp_send_video, whatsapp_send_document, whatsapp_send_sticker, whatsapp_send_location, whatsapp_send_contacts, whatsapp_send_reaction, whatsapp_send_template, whatsapp_send_reply_buttons, whatsapp_send_list, whatsapp_send_cta_url, whatsapp_send_flow

Estado: whatsapp_mark_as_read

Mídia: whatsapp_upload_media, whatsapp_get_media, whatsapp_delete_media

Templates: whatsapp_list_templates, whatsapp_create_template, whatsapp_delete_template

Perfil/conta: whatsapp_get_business_profile, whatsapp_update_business_profile, whatsapp_list_phone_numbers, whatsapp_register_phone_number, whatsapp_block_users

Messenger Platform (~14 tools)

messenger_send_text, messenger_send_quick_replies, messenger_send_attachment, messenger_send_generic_template, messenger_send_button_template, messenger_send_media_template, messenger_sender_action, messenger_upload_attachment, messenger_get_user_profile, messenger_list_conversations, messenger_set_profile, messenger_get_profile, messenger_pass_thread_control, messenger_take_thread_control

Instagram Messaging (~10 tools)

instagram_send_text, instagram_send_quick_replies, instagram_send_attachment, instagram_send_generic_template, instagram_send_button_template, instagram_send_product_template, instagram_private_reply_to_comment, instagram_react_to_message, instagram_get_user_profile, instagram_list_conversations

Webhooks (3 tools)

webhook_verify_challenge, webhook_validate_signature, webhook_parse_event

Fonte de verdade

O arquivo reference/endpoints.json é o catálogo canônico dos endpoints — gerado por crawl da documentação oficial em developers.facebook.com/documentation/business-messaging/... e developers.facebook.com/docs/messenger-platform/....

Cada tool wrapea um endpoint desse catálogo. Para adicionar suporte a um endpoint novo:

1. Adicionar entrada em reference/endpoints.json
2. Criar o tool em src/tools/<produto>.ts usando graphRequest() de src/client.ts
3. Registrar em src/index.ts (já automático via registerXxxTools)

Licença

MIT.