📅 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.
📂 Table of contents (click to expand)
🚀 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.
📂 Project Structure (click to expand)
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)
(See repo for full details — this is a high-level layout for contributors.)
🔧 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 .
# 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
| Name | Path | Description |
|---|---|---|
events_today | ffcal://events/today | Today's events |
events_week | ffcal://events/week | All events this week |
events_range | ffcal://events/range/{start}/{end} | Custom date range |
🛠️ Tools
| Name | Type | Description |
|---|---|---|
ffcal_get_calendar_events | Tool | Retrieve events for a given period |
Supported values:
today, tomorrow, yesterday, this_week, next_week, last_week, this_month, next_month, last_month, custom
📝 Prompts
| Name | Description |
|---|---|
ffcal_daily_prep | Trader prep note for today |
ffcal_weekly_outlook | Weekly macro event summary |
ffcal_volatility_grid | Weekly event-risk heatmap |
ffcal_trade_map_scenarios | Scenario map for specific events |
🧩 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
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
⚙️ Configuration Reference (click to expand)
⚙️ Configuration
| Variable | Default | Description |
|---|---|---|
NAMESPACE | ffcal | Namespace prefix |
MCP_TRANSPORT | stdio | Transport type (stdio, http, sse) |
MCP_HOST | 127.0.0.1 | Host for HTTP/SSE |
MCP_PORT | 8000 | Port for HTTP/SSE |
SCRAPER_TIMEOUT_MS | 5000 | Playwright timeout |
LOCAL_TIMEZONE | System local | Timezone override |
Example .env
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080
NAMESPACE=ffcal
🐳 Docker Integration (click to expand)
🐳 Docker Integration
Supports both stdio (default) and HTTP/SSE.
docker compose build
docker compose up forexfactory_mcp
Runs MCP server and exposes it on port 8000.
🧰 Makefile Targets (click to expand)
| Target | Description |
|---|---|
make build | Build Docker image |
make run-http | Run server in HTTP mode |
make run-stdio | Run in stdio mode |
make dev-http | Inspect via MCP Inspector |
make stop | Stop containers |
🧩 Troubleshooting Docker (click to expand)
🐍 1. uv or dependency install fails
Run:
docker compose build --no-cache forexfactory_mcp
⚡ 2. Server exits immediately
Switch to:
make run-http
🌐 3. Port in use
Change port:
docker compose run --rm -e MCP_PORT=8080 forexfactory_mcp
🔐 4. Browser fails
Install Chromium:
docker compose run forexfactory_mcp playwright install chromium
🧪 Testing & Roadmap (click to expand)
🧪 Testing
pytest -v
📊 Roadmap
- Event filters by currency and impact
- Historical backfill
- MCP prompt expansions
- Cloud-ready deployment
🤝 Contributing
- Fork the repo
- Create a feature branch
- Commit with a clear message
- Push and open a PR
📜 License
MIT License – see LICENSE for details.