📅 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.
- 📅 ForexFactory MCP Server
🚀 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.
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 .
# 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
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
Example .env
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080
NAMESPACE=ffcal
🐳 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.
🐍 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
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.