Facebook MCP Server

Automatize e gerencie interações em uma Página do Facebook usando a API do Graph do Facebook.

Documentação

Just_Facebook MCP Server

Este projeto é um servidor Model Context Protocol (MCP) para automatizar e gerenciar interações em uma Página do Facebook usando a Graph API do Facebook. Ele fornece ferramentas para criar posts, moderar comentários, obter insights de posts e filtrar feedback negativo — pronto para ser conectado ao Claude ou a qualquer outro agente baseado em LLM.

Originalmente desenvolvido a partir de @HagaiHen/facebook-mcp-server, esta versão é destinada a empacotamento e distribuição via PyPI.

🤖 O que é isso?

Este MCP fornece um conjunto de ferramentas acionáveis por IA que se conectam diretamente a uma Página do Facebook, abstraindo operações comuns da API como funções amigáveis para LLMs.

✅ Benefícios

Capacita gerentes de mídias sociais a automatizar moderação e análises.
Integra-se perfeitamente com qualquer cliente de agente.
Permite controle fino sobre o conteúdo do Facebook a partir de linguagem natural.

📦 Recursos

Ferramenta	Descrição
`post_to_facebook`	Criar um novo post no Facebook com uma mensagem.
`reply_to_comment`	Responder a um comentário específico em um post.
`get_page_posts`	Recuperar posts recentes da Página.
`get_post_comments`	Buscar comentários em um determinado post.
`delete_post`	Excluir um post específico pelo ID.
`delete_comment`	Excluir um comentário específico pelo ID.
`delete_comment_from_post`	Alias para excluir um comentário de um post específico.
`filter_negative_comments`	Filtrar comentários com palavras-chave de sentimento negativo.
`get_number_of_comments`	Contar o número de comentários em um post.
`get_number_of_likes`	Contar o número de curtidas em um post.
`get_post_impressions`	Obter o total de impressões em um post.
`get_post_impressions_unique`	Obter o número de usuários únicos que viram o post.
`get_post_impressions_paid`	Obter o número de impressões pagas no post.
`get_post_impressions_organic`	Obter o número de impressões orgânicas no post.
`get_post_engaged_users`	Obter o número de usuários que interagiram com o post.
`get_post_clicks`	Obter o número de cliques no post.
`get_post_reactions_like_total`	Obter o número total de reações 'Curtir'.
`get_post_top_commenters`	Obter os principais comentaristas de um post.
`post_image_to_facebook`	Publicar uma imagem com legenda na página do Facebook.
`send_dm_to_user`	Enviar uma mensagem direta para um usuário.
`update_post`	Atualiza a mensagem de um post existente.
`schedule_post`	Agendar um post para publicação futura.
`get_page_fan_count`	Recuperar o número total de fãs da Página.
`get_post_share_count`	Obter o número de compartilhamentos em um post.

🚀 Configuração e Instalação

1. Pré-requisitos

Este projeto requer Python 3.10+ e uv (um gerenciador de pacotes Python rápido).

Para instalar uv, execute:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clonar o Repositório

3. 🛠️ Instalar Dependências

Use a ferramenta uv com o pyproject.toml:

# Install all dependencies and create a virtual environment
uv sync

# For development (includes testing and linting tools)
uv sync --dev

4. Configurar o Ambiente

Crie um arquivo .env no diretório raiz e adicione suas credenciais da Página do Facebook:

FACEBOOK_ACCESS_TOKEN=your_facebook_page_access_token
FACEBOOK_PAGE_ID=your_page_id

Obtendo suas credenciais do Facebook

Entre no Facebook para Desenvolvedores
Escolha Desenvolvedor como seu caso de uso.
Crie um novo aplicativo.
No painel do aplicativo, vá para Personalizar Caso de Uso e selecione todas as opções.
Navegue até Ferramentas → Graph API Explorer.
Primeiro crie um Token de Acesso de Usuário — certifique-se de:

*Selecionar todas as permissões necessárias

*Associá-lo ao seu aplicativo
Em seguida, gere um Token de Acesso de Página (ele herdará as permissões).
Salve o Token de Acesso de Página e use-o no arquivo .env.

Para encontrar seu ID da Página:

Vá para sua Página do Facebook → Sobre → Role para baixo para ver o ID

⏰ Importante: Limitações do Token da API do Facebook

Os tokens de acesso do Facebook têm vida útil limitada e expirarão, fazendo com que as chamadas de API falhem. Entender essas limitações é crucial para manter seu servidor MCP.

Tipos de Token e Vida Útil:

Tipo de Token	Vida Útil	Caso de Uso
Token de Usuário de Curta Duração	1-2 horas	Somente testes
Token de Usuário de Longa Duração	60 dias	Desenvolvimento
Token de Página de Curta Duração	1-2 horas	Somente testes
Token de Página de Longa Duração	60 dias	Recomendado para MCP
Token de Usuário do Sistema	Sem expiração*	Aplicações de produção

Quando os Tokens Expirarem:

❌ Todas as ferramentas MCP retornarão erros OAuthException
❌ Mensagem de erro: "Sessão expirou"
❌ Códigos de erro: 190 (token expirado) ou 463 (sessão expirada)

Atualização Automática de Token:

Fornecemos um script para gerar facilmente tokens de longa duração (60 dias):

uv run python scripts/refresh_facebook_token.py

Este script irá:

✅ Guiá-lo pela geração do token
✅ Trocar tokens de curta duração por tokens de longa duração
✅ Atualizar seu arquivo .env automaticamente
✅ Validar o novo token

Melhores Práticas:

🔄 Atualize os tokens a cada 50 dias para evitar expiração
📅 Defina lembretes no calendário para renovação do token
🤖 Use tokens de Página de longa duração para desenvolvimento
🏢 Considere tokens de Usuário do Sistema para produção

Solução de Problemas com Tokens:

# Check if your token is expired
uv run python -c "
from just_facebook_mcp.manager import Manager
manager = Manager()
try:
    result = manager.get_page_fan_count()
    print('✅ Token is working')
except Exception as e:
    print(f'❌ Token error: {e}')
"

5. 🏃‍♂️ Executando o Servidor

# Option 1: Using the script entry point (recommended)
uv run just_facebook_mcp

# Option 2: Run the Python module directly
uv run python -m just_facebook_mcp.server

# Option 3: Activate virtual environment first
source .venv/bin/activate
python -m just_facebook_mcp.server

🧩 Usando com o Claude Desktop

Para integrar com o Claude Desktop:

Abra o Claude Desktop
Vá para Configurações → Desenvolvedor → Editar Configuração

Configuração rápida com uvx

Você pode usar o servidor MCP sem instalar localmente com uvx:

Adicione o seguinte à sua configuração MCP:

{
  "mcpServers": {
    "just_facebook_mcp": {
      "command": "uvx",
      "args": [
        "just_facebook_mcp"
      ],
      "env": {
        "FACEBOOK_ACCESS_TOKEN": "<put_your_FB_token_here>",
        "FACEBOOK_PAGE_ID": "<put_your_page_id_here>"
      }
    }
  }
}

Configuração local de desenvolvimento:

Se você já clonou o servidor MCP via git, pode configurá-lo localmente.

Adicione o seguinte à sua configuração MCP:

Opção 1: Usando o ponto de entrada do pacote (recomendado)

{
  "mcpServers": {
    "just_facebook_mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/just_facebook_mcp-server",
        "just_facebook_mcp"
      ]
    }
  }
}

Opção 2: Usando o módulo Python

{
  "mcpServers": {
    "just_facebook_mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/just_facebook_mcp-server",
        "python",
        "-m",
        "just_facebook_mcp.server"
      ]
    }
  }
}

Opção 3: Se instalado via pip

{
  "mcpServers": {
    "just_facebook_mcp": {
      "command": "just_facebook_mcp"
    }
  }
}

Substitua /absolute/path/to/just_facebook_mcp-server pelo caminho real do seu projeto.

🔧 Desenvolvimento

Executando Testes

uv run pytest

Formatação de Código

uv run black .

Verificação de Tipos

uv run mypy .

Instalar Dependências de Desenvolvimento

uv sync --dev

✅ Você Está Pronto!

Seu servidor MCP do Facebook está agora configurado e pronto para alimentar o Claude Desktop! Você pode:

✨ Criar posts por meio de linguagem natural

📊 Obter análises e insights

💬 Moderar comentários automaticamente

🎯 Agendar conteúdo

📈 Acompanhar métricas de engajamento

🤝 Contribuindo

Contribuições, problemas e solicitações de recursos são bem-vindos!

📄 Licença Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.