📅 ForexFactory MCP-Server

Ein MCP-Server (Model Context Protocol), der ForexFactory-Wirtschaftskalenderdaten als Ressourcen und Tools bereitstellt.

Entwickelt für den Einsatz in agentenbasierten Workflows, LLMs und Trading-Assistenten.

• 📅 ForexFactory MCP-Server

  • 🚀 Funktionen

    • 📌 Entwicklungsstatus

  • 🔧 Installation

    • Anforderungen

    • Einrichtung

  • ▶️ Verwendung

    • ⚡ Schnellstart

    • SSE-Transport (⚠️ veraltet)

    • Standardwerte für Umgebungsvariablen

  • 🏷️ Namespace

  • 📦 Ressourcen

  • 🛠️ Tools

  • 📝 Prompts

    • 🧩 Prompt-Stile

  • 💻 Client-Beispiele

    • Beispiel: Verwendung der MCP-CLI

    • Beispiel: Verwendung in Python

    • Beispiel: LangChain-Integration

    • 📘 Referenz zur Client-Konfiguration

  • ⚙️ Konfiguration

    • Beispiel .env

  • 🐳 Docker-Integration

    • 🐍 1. uv oder Abhängigkeitsinstallation schlägt fehl

    • ⚡ 2. Server beendet sich sofort

    • 🌐 3. Port wird bereits verwendet

    • 🔐 4. Browser schlägt fehl

  • 🧪 Tests

  • 📊 Roadmap

  • 🤝 Mitwirken

  • 📜 Lizenz

🚀 Funktionen

• ✅ Abrufen von Wirtschaftskalender-Ereignissen nach Zeitraum (today, this_week, custom usw.)

• ✅ Zugriff über MCP-Ressourcen (für abonnementartigen Zugriff)

• ✅ Zugriff über MCP-Tools (direkte Aufrufe von Clients/Agenten)

• ✅ JSON-basierte Antworten für einfache Integration

• ⚡ Integrierbar mit LangChain, n8n oder jedem MCP-kompatiblen Client

📌 Entwicklungsstatus

Dieses Projekt befindet sich in aktiver Entwicklung. Die Kernfunktionalität ist stabil (Abrufen von ForexFactory-Wirtschaftskalender-Ereignissen über MCP-Tools und -Ressourcen), aber wir arbeiten noch an:

• Erweiterung der Funktionen (Prompts, Bereitstellungsoptionen)

• Verbesserung der Dokumentation und Beispiele

Wir freuen uns über Feedback und Beiträge, während wir das Ökosystem weiter ausbauen.

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)

(Siehe Repository für vollständige Details – dies ist ein grober Überblick für Mitwirkende.)

Related MCP server: Google-Calendar Universal MCP

🔧 Installation

Anforderungen

• Python 3.12+

• uv oder pip

• Ein modernes Terminal oder ein MCP-kompatibler Client

Einrichtung

# 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

▶️ Verwendung

⚡ Schnellstart

Starten Sie den Server mit den Standardeinstellungen (stdio-Transport):

uv run ffcal-server

Ausführung mit HTTP-Transport:

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

SSE-Transport (⚠️ veraltet)

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

Standardwerte für Umgebungsvariablen

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080

🏷️ Namespace

Standard-Namespace:

ffcal

Überschreiben via .env:

NAMESPACE=ffcal

📦 Ressourcen

🛠️ Tools

Unterstützte Werte:

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

📝 Prompts

🧩 Prompt-Stile

Alle Prompts unterstützen einen style-Parameter zur Steuerung der Formatierung. Standard:

style: str = "bullet points"

Siehe die Output Style Reference für verfügbare Formate.

💻 Client-Beispiele

Beispiel: Verwendung der MCP-CLI

mcp call ffcal:get_calendar_events time_period=this_week

Beispiel: Verwendung in 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)

Beispiel: LangChain-Integration

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)

📘 Referenz zur Client-Konfiguration

📖 docs/CLIENT_CONFIG_REFERENCE.md

Beinhaltet:

• ✅ Beispielkonfigurationen für Claude Desktop (lokal + Docker)

• 🐳 Docker-Build und -Einrichtung

• 🧩 VS Code MCP-Integration (zukünftig)

• 🧪 Test- und Fehlerbehebungs-Checkliste

• 🔍 Inspector-Einrichtung für visuelles Debugging

⚙️ Konfiguration

Beispiel .env

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

🐳 Docker-Integration

Unterstützt sowohl stdio (Standard) als auch HTTP/SSE.

docker compose build
docker compose up forexfactory_mcp

Führt den MCP-Server aus und stellt ihn auf Port 8000 bereit.

🐍 1. uv oder Abhängigkeitsinstallation schlägt fehl

Ausführen:

docker compose build --no-cache forexfactory_mcp

⚡ 2. Server beendet sich sofort

Wechseln zu:

make run-http

🌐 3. Port wird bereits verwendet

Port ändern:

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

🔐 4. Browser schlägt fehl

Chromium installieren:

docker compose run forexfactory_mcp playwright install chromium

🧪 Tests

pytest -v

📊 Roadmap

• [ ] Ereignisfilter nach Währung und Auswirkung

• [ ] Historische Daten nachladen

• [ ] MCP-Prompt-Erweiterungen

• [ ] Cloud-fähige Bereitstellung

🤝 Mitwirken

1. Forke das Repo

2. Erstelle einen Feature-Branch

3. Committe mit einer klaren Nachricht

4. Pushe und öffne einen PR

📜 Lizenz

MIT-Lizenz – siehe LICENSE für Details.