Just Facebook

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

Documentação

Servidor MCP Just_Facebook

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 publicações, moderar comentários, buscar insights de publicações 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 ao empacotamento e distribuição via PyPI.

🤖 O Que É Isto?

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 LLM.

✅ Benefícios

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

📦 Recursos

Ferramenta	Descrição
`post_to_facebook`	Criar uma nova publicação no Facebook com uma mensagem.
`reply_to_comment`	Responder a um comentário específico em uma publicação.
`get_page_posts`	Recuperar publicações recentes da Página.
`get_post_comments`	Buscar comentários em uma determinada publicação.
`delete_post`	Excluir uma publicação específica por ID.
`delete_comment`	Excluir um comentário específico por ID.
`delete_comment_from_post`	Alias para excluir um comentário de uma publicação específica.
`filter_negative_comments`	Filtrar comentários com palavras-chave de sentimento negativo.
`get_number_of_comments`	Contar o número de comentários em uma publicação.
`get_number_of_likes`	Contar o número de curtidas em uma publicação.
`get_post_impressions`	Obter o total de impressões em uma publicação.
`get_post_impressions_unique`	Obter o número de usuários únicos que viram a publicação.
`get_post_impressions_paid`	Obter o número de impressões pagas na publicação.
`get_post_impressions_organic`	Obter o número de impressões orgânicas na publicação.
`get_post_engaged_users`	Obter o número de usuários que interagiram com a publicação.
`get_post_clicks`	Obter o número de cliques na publicação.
`get_post_reactions_like_total`	Obter o número total de reações 'Curtir'.
`get_post_top_commenters`	Obter os principais comentaristas de uma publicação.
`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 uma publicação existente.
`schedule_post`	Agendar uma publicação para divulgaçã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 uma publicação.

🚀 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

Faça login no Facebook for Developers
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. Compreender 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*	Aplicativos 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á:

✅ Orientá-lo na 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

Boas Práticas:

🔄 Atualize os tokens a cada 50 dias para evitar expiração
📅 Defina lembretes no calendário para renovação de tokens
🤖 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 instalação local 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 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 para Começar!

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

✨ Criar publicações 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 está licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.