Skip to main content
Glama

ForexFactory MCP Server

by kjpou1
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

📅 ForexFactory MCP Server

Python License MCP uv

Contributions welcome Status PRs Welcome Made with Love

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.

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

📖 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

⚙️ 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

Supports both stdio (default) and HTTP/SSE.

docker compose build docker compose up forexfactory_mcp

Runs MCP server and exposes it on port 8000.

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

🐍 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

  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.

Deploy Server
-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

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.

Tools

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.

  1. 🚀 Features
    1. 📌 Development Status
  2. 🔧 Installation
    1. Requirements
    2. Setup
  3. ▶️ Usage
    1. ⚡ Quickstart
    2. SSE transport (⚠️ deprecated)
    3. Environment variable defaults
  4. 🏷️ Namespace
    1. 📦 Resources
      1. 🛠️ Tools
        1. 📝 Prompts
          1. 🧩 Prompt Styles
        2. 💻 Client Examples
          1. Example: Using MCP CLI
          2. Example: Using in Python
          3. Example: LangChain Integration
          4. 📘 Client Configuration Reference
        3. ⚙️ Configuration
          1. Example .env
        4. 🐳 Docker Integration
          1. 🐍 1. uv or dependency install fails
          2. ⚡ 2. Server exits immediately
          3. 🌐 3. Port in use
          4. 🔐 4. Browser fails
        5. 🧪 Testing
          1. 📊 Roadmap
            1. 🤝 Contributing
              1. 📜 License

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/kjpou1/forexfactory-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server