Facebook MCP Server

Automatiza y gestiona interacciones en una página de Facebook usando la API Graph de Facebook.

Documentación

Just_Facebook MCP Server

Este proyecto es un servidor de Model Context Protocol (MCP) para automatizar y gestionar interacciones en una Página de Facebook utilizando la API Graph de Facebook. Proporciona herramientas para crear publicaciones, moderar comentarios, obtener estadísticas de publicaciones y filtrar comentarios negativos, listo para conectarse a Claude o cualquier otro agente basado en LLM.

Desarrollado originalmente a partir de @HagaiHen/facebook-mcp-server, esta versión está pensada para empaquetarse y distribuirse a través de PyPI.

🤖 ¿Qué es esto?

Este MCP proporciona un conjunto de herramientas invocables por IA que se conectan directamente a una Página de Facebook, abstraiendo operaciones comunes de la API como funciones amigables para LLMs.

✅ Beneficios

Permite a los gestores de redes sociales automatizar la moderación y el análisis.
Se integra perfectamente con cualquier cliente de Agent.
Permite un control detallado del contenido de Facebook mediante lenguaje natural.

📦 Características

Herramienta	Descripción
`post_to_facebook`	Crear una nueva publicación en Facebook con un mensaje.
`reply_to_comment`	Responder a un comentario específico en una publicación.
`get_page_posts`	Obtener publicaciones recientes de la Página.
`get_post_comments`	Obtener comentarios de una publicación determinada.
`delete_post`	Eliminar una publicación específica por ID.
`delete_comment`	Eliminar un comentario específico por ID.
`delete_comment_from_post`	Alias para eliminar un comentario de una publicación específica.
`filter_negative_comments`	Filtrar comentarios con palabras clave de sentimiento negativo.
`get_number_of_comments`	Contar el número de comentarios en una publicación.
`get_number_of_likes`	Contar el número de "Me gusta" en una publicación.
`get_post_impressions`	Obtener las impresiones totales de una publicación.
`get_post_impressions_unique`	Obtener el número de usuarios únicos que vieron la publicación.
`get_post_impressions_paid`	Obtener el número de impresiones pagadas en la publicación.
`get_post_impressions_organic`	Obtener el número de impresiones orgánicas en la publicación.
`get_post_engaged_users`	Obtener el número de usuarios que interactuaron con la publicación.
`get_post_clicks`	Obtener el número de clics en la publicación.
`get_post_reactions_like_total`	Obtener el número total de reacciones "Me gusta".
`get_post_top_commenters`	Obtener los principales comentaristas de una publicación.
`post_image_to_facebook`	Publicar una imagen con un pie de foto en la página de Facebook.
`send_dm_to_user`	Enviar un mensaje directo a un usuario.
`update_post`	Actualiza el mensaje de una publicación existente.
`schedule_post`	Programar una publicación para su publicación futura.
`get_page_fan_count`	Obtener el número total de seguidores de la Página.
`get_post_share_count`	Obtener el número de veces que se compartió una publicación.

🚀 Configuración e Instalación

1. Requisitos previos

Este proyecto requiere Python 3.10+ y uv (un gestor de paquetes de Python rápido).

Para instalar uv, ejecuta:

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

2. Clonar el Repositorio

3. 🛠️ Instalar Dependencias

Usa la herramienta uv con pyproject.toml:

# Install all dependencies and create a virtual environment
uv sync

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

4. Configurar el Entorno

Crea un archivo .env en el directorio raíz y añade tus credenciales de la Página de Facebook:

FACEBOOK_ACCESS_TOKEN=your_facebook_page_access_token
FACEBOOK_PAGE_ID=your_page_id

Cómo obtener tus credenciales de Facebook

Inicia sesión en Facebook para Desarrolladores
Elige Desarrollador como tu caso de uso.
Crea una nueva aplicación.
En el panel de la aplicación, ve a Personalizar Caso de Uso y selecciona todas las opciones.
Navega a Herramientas → Explorador de API Graph.
Primero crea un Token de Acceso de Usuario — asegúrate de:

*Seleccionar todos los permisos requeridos

*Asociarlo con tu aplicación
Luego genera un Token de Acceso de Página (este heredará los permisos).
Guarda el Token de Acceso de Página y úsalo en el archivo .env.

Para encontrar tu ID de Página:

Ve a tu Página de Facebook → Acerca de → Desplázate hacia abajo para ver el ID

⏰ Importante: Limitaciones del Token de la API de Facebook

Los tokens de acceso de Facebook tienen una vida útil limitada y caducarán, lo que provocará fallos en las llamadas a la API. Comprender estas limitaciones es crucial para mantener tu servidor MCP.

Tipos de Token y su Duración:

Tipo de Token	Duración	Caso de Uso
Token de Usuario de Corta Duración	1-2 horas	Solo pruebas
Token de Usuario de Larga Duración	60 días	Desarrollo
Token de Página de Corta Duración	1-2 horas	Solo pruebas
Token de Página de Larga Duración	60 días	Recomendado para MCP
Token de Usuario del Sistema	Sin caducidad*	Aplicaciones de producción

Cuando Caducan los Tokens:

❌ Todas las herramientas MCP devolverán errores OAuthException
❌ Mensaje de error: "La sesión ha caducado"
❌ Códigos de error: 190 (token caducado) o 463 (sesión caducada)

Renovación Automática de Tokens:

Proporcionamos un script para generar fácilmente tokens de larga duración (60 días):

uv run python scripts/refresh_facebook_token.py

Este script:

✅ Te guiará en la generación del token
✅ Intercambiará tokens de corta duración por tokens de larga duración
✅ Actualizará tu archivo .env automáticamente
✅ Validará el nuevo token

Mejores Prácticas:

🔄 Renueva los tokens cada 50 días para evitar la caducidad
📅 Configura recordatorios en el calendario para la renovación de tokens
🤖 Usa tokens de Página de larga duración para desarrollo
🏢 Considera tokens de Usuario del Sistema para producción

Solución de Problemas con 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. 🏃‍♂️ Ejecutar el 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

🧩 Uso con Claude Desktop

Para integrarte con Claude Desktop:

Abre Claude Desktop
Ve a Configuración → Desarrollador → Editar Configuración

Configuración rápida con uvx

Puedes usar el servidor MCP sin instalarlo localmente con uvx:

Añade lo siguiente a tu configuración de 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>"
      }
    }
  }
}

Configuración local de desarrollo:

Si ya has clonado el servidor MCP con git, puedes configurarlo localmente.

Añade lo siguiente a tu configuración de MCP:

Opción 1: Usando el punto de entrada del paquete (recomendado)

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

Opción 2: Usando el módulo de Python

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

Opción 3: Si se instaló mediante pip

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

Reemplaza /absolute/path/to/just_facebook_mcp-server con la ruta real de tu proyecto.

🔧 Desarrollo

Ejecutar Pruebas

uv run pytest

Formato de Código

uv run black .

Verificación de Tipos

uv run mypy .

Instalar Dependencias de Desarrollo

uv sync --dev

✅ ¡Estás Listo para Empezar!

Tu servidor MCP de Facebook está ahora configurado y listo para potenciar Claude Desktop. Puedes:

✨ Crear publicaciones mediante lenguaje natural

📊 Obtener análisis y estadísticas

💬 Moderar comentarios automáticamente

🎯 Programar contenido

📈 Realizar seguimiento de métricas de interacción

🤝 Contribuciones

¡Las contribuciones, problemas y solicitudes de funciones son bienvenidos!

📄 Licencia Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.