📅 Servidor MCP de ForexFactory

Un servidor MCP (Model Context Protocol) que expone datos del calendario económico de ForexFactory como recursos y herramientas.

Diseñado para su uso en flujos de trabajo de agentes, LLMs y asistentes de trading.

• 📅 Servidor MCP de ForexFactory

  • 🚀 Características

    • 📌 Estado del desarrollo

  • 🔧 Instalación

    • Requisitos

    • Configuración

  • ▶️ Uso

    • ⚡ Inicio rápido

    • Transporte SSE (⚠️ obsoleto)

    • Valores predeterminados de variables de entorno

  • 🏷️ Espacio de nombres

  • 📦 Recursos

  • 🛠️ Herramientas

  • 📝 Prompts

    • 🧩 Estilos de prompt

  • 💻 Ejemplos de cliente

    • Ejemplo: Usando la CLI de MCP

    • Ejemplo: Usando en Python

    • Ejemplo: Integración con LangChain

    • 📘 Referencia de configuración del cliente

  • ⚙️ Configuración

    • Ejemplo .env

  • 🐳 Integración con Docker

    • 🐍 1. Falla la instalación de uv o dependencias

    • ⚡ 2. El servidor se cierra inmediatamente

    • 🌐 3. Puerto en uso

    • 🔐 4. Falla el navegador

  • 🧪 Pruebas

  • 📊 Hoja de ruta

  • 🤝 Contribuciones

  • 📜 Licencia

🚀 Características

• ✅ Recuperar eventos del calendario económico por período de tiempo (today, this_week, custom, etc.)

• ✅ Acceso mediante recursos MCP (para acceso tipo suscripción)

• ✅ Acceso mediante herramientas MCP (llamadas directas desde clientes/agentes)

• ✅ Respuestas centradas en JSON para una fácil integración

• ⚡ Se integra con LangChain, n8n o cualquier cliente compatible con MCP

📌 Estado del desarrollo

Este proyecto está en desarrollo activo. La funcionalidad principal es estable (recuperar eventos del calendario económico de ForexFactory mediante herramientas y recursos MCP), pero todavía estamos:

• Ampliando funciones (prompts, opciones de despliegue)

• Mejorando la documentación y los ejemplos

Agradecemos los comentarios y las contribuciones mientras continuamos construyendo el ecosistema.

forexfactory-mcp/
│── src/forexfactory_mcp/   # Main package
│   ├── models/             # Schemas & enums
│   ├── services/           # Scraper + data normalization
│   ├── tools/              # MCP tool definitions
│   ├── resources/          # MCP resource definitions
│   ├── prompts/            # Prompt templates (optional MCP prompts)
│   ├── utils/              # Shared helpers & config
│   └── server.py           # FastMCP server entrypoint
│
│── examples/               # Example clients
│── tests/                  # Unit tests
│── .env.example            # Copy to .env for config
│── pyproject.toml          # Dependencies & metadata
│── README.md               # Documentation
│── .python-version         # Python version pin (3.12)

(Consulta el repositorio para obtener todos los detalles; este es un diseño de alto nivel para colaboradores.)

Related MCP server: Google-Calendar Universal MCP

🔧 Instalación

Requisitos

• Python 3.12+

• uv o pip

• Un terminal moderno o un cliente compatible con MCP

Configuración

# Clone repo
git clone https://github.com/kjpou1/forexfactory-mcp.git
cd forexfactory-mcp

# Install dependencies
uv sync   # or: pip install -e .

# Install Playwright browser binaries
uv run playwright install chromium
# or, if using pip/venv:
playwright install chromium

# Copy example environment and adjust if needed
cp .env.example .env

▶️ Uso

⚡ Inicio rápido

Inicia el servidor con la configuración predeterminada (transporte stdio):

uv run ffcal-server

Ejecuta con transporte HTTP:

uv run ffcal-server --transport http --host 0.0.0.0 --port 8080

Transporte SSE (⚠️ obsoleto)

uv run ffcal-server --transport sse --host 127.0.0.1 --port 8001

Valores predeterminados de variables de entorno

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080

🏷️ Espacio de nombres

Espacio de nombres predeterminado:

ffcal

Anular mediante .env:

NAMESPACE=ffcal

📦 Recursos

🛠️ Herramientas

Valores admitidos:

today, tomorrow, yesterday, this_week, next_week, last_week, this_month, next_month, last_month, custom

📝 Prompts

🧩 Estilos de prompt

Todos los prompts admiten un parámetro style para controlar el formato. Predeterminado:

style: str = "bullet points"

Consulta la Referencia de estilo de salida para ver los formatos disponibles.

💻 Ejemplos de cliente

Ejemplo: Usando la CLI de MCP

mcp call ffcal:get_calendar_events time_period=this_week

Ejemplo: Usando en Python

from mcp.client.session import Session
async with Session("ws://localhost:8000") as session:
    result = await session.call_tool("ffcal:get_calendar_events", {"time_period": "today"})
    print(result)

Ejemplo: Integración con LangChain

from langchain.agents import initialize_agent
from langchain_mcp import MCPToolkit

toolkit = MCPToolkit.from_server_url("ws://localhost:8000", namespace="ffcal")
agent = initialize_agent(toolkit.tools)
response = agent.run("What are today's USD-related high impact events?")
print(response)

📘 Referencia de configuración del cliente

📖 docs/CLIENT_CONFIG_REFERENCE.md

Incluye:

• ✅ Configuraciones de ejemplo para Claude Desktop (local + Docker)

• 🐳 Construcción y configuración de Docker

• 🧩 Integración de MCP en VS Code (futuro)

• 🧪 Lista de verificación de pruebas y solución de problemas

• 🔍 Configuración del inspector para depuración visual

⚙️ Configuración

Ejemplo .env

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080
NAMESPACE=ffcal

🐳 Integración con Docker

Admite tanto stdio (predeterminado) como HTTP/SSE.

docker compose build
docker compose up forexfactory_mcp

Ejecuta el servidor MCP y lo expone en el puerto 8000.

🐍 1. Falla la instalación de uv o dependencias

Ejecuta:

docker compose build --no-cache forexfactory_mcp

⚡ 2. El servidor se cierra inmediatamente

Cambia a:

make run-http

🌐 3. Puerto en uso

Cambia el puerto:

docker compose run --rm -e MCP_PORT=8080 forexfactory_mcp

🔐 4. Falla el navegador

Instala Chromium:

docker compose run forexfactory_mcp playwright install chromium

🧪 Pruebas

pytest -v

📊 Hoja de ruta

• [ ] Filtros de eventos por moneda e impacto

• [ ] Relleno de datos históricos

• [ ] Expansiones de prompts de MCP

• [ ] Despliegue listo para la nube

🤝 Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de funciones

3. Confirma con un mensaje claro

4. Envía y abre un PR

📜 Licencia

Licencia MIT: consulta LICENSE para obtener más detalles.