📅 ForexFactory MCP Server

An MCP (Model Context Protocol) server that exposes ForexFactory economic calendar data as resources and tools.

Designed for use in agentic workflows, LLMs, and trading assistants.

---

---

🚀 Features

• ✅ Retrieve economic calendar events by time period (today, this_week, custom, etc.)
• ✅ Access via MCP resources (for subscription-style access)
• ✅ Access via MCP tools (direct calls from clients/agents)
• ✅ JSON-first responses for easy integration
• ⚡ Integrates with LangChain, n8n, or any MCP-compatible client

---

📌 Development Status

This project is actively developed. The core functionality is stable (retrieving ForexFactory economic calendar events via MCP tools and resources), but we are still:

• Expanding features (prompts, deployment options)
• Improving documentation and examples

We welcome feedback and contributions while we continue building out the ecosystem.

---

---

🔧 Installation

Requirements

• Python 3.12+
• uv or pip
• A modern terminal or MCP-compatible client

Setup

# 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

---

▶️ Usage

⚡ Quickstart

Start the server with default settings (stdio transport):

uv run ffcal-server

Run with HTTP transport:

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

---

SSE transport (⚠️ deprecated)

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

---

Environment variable defaults

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080

---

🏷️ Namespace

Default namespace:

ffcal

Override via .env:

NAMESPACE=ffcal

---

📦 Resources

---

🛠️ Tools

Supported values:

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

---

📝 Prompts

---

🧩 Prompt Styles

All prompts support a style parameter to control formatting. Default:

style: str = "bullet points"

See the Output Style Reference for available formats.

---

💻 Client Examples

Example: Using MCP CLI

mcp call ffcal:get_calendar_events time_period=this_week

Example: Using 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)

Example: 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)

---

📘 Client Configuration Reference

📖 docs/CLIENT_CONFIG_REFERENCE.md

Includes:

• ✅ Example configs for Claude Desktop (local + Docker)
• 🐳 Docker build and setup
• 🧩 VS Code MCP integration (future)
• 🧪 Testing + troubleshooting checklist
• 🔍 Inspector setup for visual debugging

---

---

---

---

---

---

🤝 Contributing

1. Fork the repo
2. Create a feature branch
3. Commit with a clear message
4. Push and open a PR

---

📜 License

MIT License – see LICENSE for details.