Integrates with LangChain agents through MCPToolkit, enabling AI agents to access ForexFactory economic calendar data for trading and financial analysis workflows
Provides MCP-compatible access to ForexFactory economic calendar events for automation workflows and trading pipelines
📅 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.
📂 Project Structure
(See repo for full details — this is a high-level layout for contributors.)
🔧 Installation
Requirements
Python 3.12+ (see
.python-versionfor exact version)uv or pip
A modern terminal or MCP-compatible client
Setup
▶️ Usage
Start the MCP server
The server will expose MCP resources, prompts, and tools that clients can call.
🏷️ Namespace
This MCP server registers under the namespace:
You can override this in your .env file:
All tools and resources are exposed with this prefix.
Examples:
ffcal:get_calendar_eventsffcal:events_weekffcal:events_today
🛠️ Tools & Resources
Name | Type | Description | Parameters |
| Resource | Fetch today’s calendar events | None |
| Resource | Fetch this week’s events | None |
| Tool | Retrieve events for a given period |
(str),
(YYYY-MM-DD),
(YYYY-MM-DD) |
Supported time_period values
When custom is used, you must pass start_date and end_date.
💻 Client Examples
Example: Using MCP CLI
Example: Using in Python
Example: LangChain Integration
⚙️ Configuration
No special config is required, but you may set environment variables.
Variable | Default | Description |
|
| MCP namespace for tools/resources |
|
| Timeout for Playwright (milliseconds) |
| system local (fallback UTC) | Local timezone override (e.g.,
) |
| (empty → default fields) | Comma-separated list of fields to include, or
for all fields |
| (empty → none) | Comma-separated list of fields to exclude (applied after INCLUDE_FIELDS) |
Include/Exclude Fields
You can control which event fields are returned by the MCP server using
INCLUDE_FIELDS and EXCLUDE_FIELDS.
Processing Rules
If both are empty → the server returns a default lean set:
id, title, currency, impact, datetime, forecast, previous, actualIf
INCLUDE_FIELDS=*→ all available fields are included.If
INCLUDE_FIELDS→ only the specified fields are included. Example:INCLUDE_FIELDS=id,name,currency,date,forecast,previous,actualIf both →
First, apply
INCLUDE_FIELDS.Then, remove any fields listed in
EXCLUDE_FIELDS.
Example Configurations
Supported Fields
Category | Fields |
Identity |
,
,
,
,
,
|
Titles |
,
,
|
Metadata |
,
,
,
|
Links |
,
,
,
,
|
Status Flags |
,
,
,
,
,
,
,
|
Impact |
,
,
,
|
Timing |
,
,
,
|
Values |
,
,
,
,
,
,
|
Display |
,
,
,
,
,
,
,
,
|
Example .env
🧪 Testing
📊 Roadmap
Event filters by currency and impact
Historical event backfill
In-memory caching (to reduce repeated scraping)
Docker container for deployment
MCP prompts for querying events in natural language
🤝 Contributing
Fork this repo
Create a feature branch:
git checkout -b feature/my-featureCommit changes:
git commit -m "Add my feature"Push branch:
git push origin feature/my-featureOpen a Pull Request
📜 License
MIT License – see LICENSE for details.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables access to ForexFactory economic calendar data through MCP resources and tools. Supports retrieving economic events by time periods for integration with trading assistants and agentic workflows.