📅 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

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+ (see .python-version for exact version)
• 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

Start the MCP server

uv run forexfactory_mcp.server

The server will expose MCP resources, prompts, and tools that clients can call.

---

🏷️ Namespace

This MCP server registers under the namespace:

ffcal

You can override this in your .env file:

NAMESPACE=ffcal

All tools and resources are exposed with this prefix.

Examples:

• ffcal_get_calendar_events
• ffcal:events_week
• ffcal:events_today

---

📦 Resources

Resources expose economic calendar events for fixed time windows or a custom date range. They are useful for streaming or subscription-based access to calendar data.

Name	Path	Description
events_today	ffcal://events/today	Economic calendar events scheduled for today
events_yesterday	ffcal://events/yesterday	Events from yesterday
events_tomorrow	ffcal://events/tomorrow	Events scheduled for tomorrow
events_week	ffcal://events/week	All events this week
events_this_week	ffcal://events/this_week	Explicit alias for this week’s events
events_next_week	ffcal://events/next_week	All events scheduled for next week
events_last_week	ffcal://events/last_week	Events from last week
events_this_month	ffcal://events/this_month	All events scheduled for this month
events_next_month	ffcal://events/next_month	All events scheduled for next month
events_last_month	ffcal://events/last_month	Events from last month
events_range	ffcal://events/range/{start}/{end}	Custom date range (YYYY-MM-DD to YYYY-MM-DD)

---

🛠️ Tools

Tools are direct, parameterized calls that allow you to query economic events dynamically.

Name	Type	Description	Parameters
ffcal_get_calendar_events	Tool	Retrieve events for a given period	time_period (str), start_date (YYYY-MM-DD), end_date (YYYY-MM-DD)

Supported time_period values

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

When custom is used, you must also pass start_date and end_date.

---

📝 Prompts

Unlike resources (which return structured event data) and tools (which query events dynamically), prompts generate structured text outputs — trader notes, playbooks, and scenario analyses — that can be directly integrated into workflows or reports.

All prompt names are prefixed with the configured namespace (default: ffcal_). If you override NAMESPACE in your .env, replace the prefix accordingly.

Name	Description	Why Use
ffcal_daily_prep	Summarize today’s calendar into a trader prep note.	Quick morning scan to know which events matter today.
ffcal_daily_playbook	Generate an FX daily trading playbook for today.	Structured trade plan aligned with key macro drivers.
ffcal_weekly_outlook	Summarize upcoming week’s high-impact events.	Helps prepare positioning for the week ahead.
ffcal_weekly_outlook_next_week	Draft a Sunday note for next week’s events.	Pre-market research note for weekend review.
ffcal_cross_asset_radar	Cross-asset spillover radar relevant to FX markets.	Highlights risks from equities, bonds, and commodities that may spill into FX.
ffcal_positioning_flow_note	Note on positioning, ETF flows, and options expiries.	Capture sentiment and positioning context beyond the economic calendar.
ffcal_volatility_grid	Weekly event-risk heatmap presented as a grid.	Visualize which days/times carry the most volatility risk.
ffcal_trade_map_scenarios	Scenario map for a chosen event with trading implications.	Anticipate market reactions and map trade scenarios ahead of the release.

---

💻 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)

---

⚙️ Configuration

No special config is required, but you may set environment variables.

Variable	Default	Description
NAMESPACE	ffcal	MCP namespace for tools/resources
SCRAPER_TIMEOUT_MS	5000	Timeout for Playwright (milliseconds)
LOCAL_TIMEZONE	system local (fallback UTC)	Local timezone override (e.g., Europe/Luxembourg)
INCLUDE_FIELDS	(empty → default fields)	Comma-separated list of fields to include, or * for all fields
EXCLUDE_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

1. If both are empty → the server returns a default lean set:

   id, title, currency, impact, datetime, forecast, previous, actual
   

2. If INCLUDE_FIELDS=* → all available fields are included.

3. If INCLUDE_FIELDS is set → only the specified fields are included. Example:

   INCLUDE_FIELDS=id,name,currency,date,forecast,previous,actual
   

4. If both INCLUDE_FIELDS and EXCLUDE_FIELDS are set →

   • First, apply INCLUDE_FIELDS.
   • Then, remove any fields listed in EXCLUDE_FIELDS.

Example Configurations

# Default lean set (no INCLUDE/EXCLUDE set)
INCLUDE_FIELDS=
EXCLUDE_FIELDS=

# All fields
INCLUDE_FIELDS=*
EXCLUDE_FIELDS=

# Minimal fields
INCLUDE_FIELDS=id,name,currency,date,forecast,previous,actual

# Include impact fields, but exclude noisy metadata
INCLUDE_FIELDS=impactName,impactClass,date,currency
EXCLUDE_FIELDS=dateline,hasLinkedThreads

---

Supported Fields

Category	Fields
Identity	id, ebaseId, title, name, prefixedName, trimmedPrefixedName
Titles	soloTitle, soloTitleFull, soloTitleShort
Metadata	notice, dateline, country, currency
Links	url, soloUrl, editUrl, hasLinkedThreads, siteId
Status Flags	hasNotice, hasDataValues, hasGraph, checkedIn, isMasterList, firstInDay, greyed, upNext
Impact	impact, impactName, impactClass, impactTitle
Timing	datetime, timeLabel, timeMasked, date
Values	actual, previous, revision, forecast, leaked, actualBetterWorse, revisionBetterWorse
Display	showGridLine, hideHistory, hideSoloPage, showDetails, showGraph, enableDetailComponent, enableExpandComponent, enableActualComponent, showExpanded

---

Example .env

# =====================================================
# 🌐 MCP Namespace
# =====================================================
# Namespace prefix for all tools and resources.
# Default: ffcal
NAMESPACE=ffcal

# =====================================================
# ⚙️ Scraper Configuration
# =====================================================
# Timeout for Playwright in milliseconds
# Default: 5000 (5s)
SCRAPER_TIMEOUT_MS=2000

# Local timezone override (uses system local if not set)
# Example: Europe/Luxembourg
#LOCAL_TIMEZONE=Europe/Luxembourg

# =====================================================
# 📊 Event Fields
# =====================================================
# Control which fields to include/exclude in normalized event data.
# - If both are empty, only the default lean set of fields is included.
# - If INCLUDE_FIELDS=* → all fields are included.
# - If both are set, INCLUDE_FIELDS is applied first, then EXCLUDE_FIELDS removes fields.

INCLUDE_FIELDS=
EXCLUDE_FIELDS=

# Example usage:
# INCLUDE_FIELDS=id,name,country,currency,date,actual,forecast,previous
# EXCLUDE_FIELDS=notice,dateline,hasLinkedThreads,checkedIn,firstInDay

---

🧪 Testing

pytest -v

---

📊 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

1. Fork this repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit changes: git commit -m "Add my feature"
4. Push branch: git push origin feature/my-feature
5. Open a Pull Request

---

📜 License

MIT License – see LICENSE for details.