Skip to main content
Glama
ForexFactory MCP Server

ForexFactory MCP Server

by kjpou1

📅 ForexFactory MCP 服务器

Python License MCP uv

Contributions welcome Status PRs Welcome Made with Love

一个将 ForexFactory 经济日历数据作为资源和工具公开的 MCP(模型上下文协议)服务器。

专为智能代理工作流、大语言模型(LLM)和交易助手设计。



🚀 功能特性

  • ✅ 按时间段(today、this_week、custom 等)检索经济日历事件

  • ✅ 通过 MCP 资源访问(用于订阅式访问)

  • ✅ 通过 MCP 工具访问(直接从客户端/代理调用)

  • ✅ 以 JSON 为主的响应,便于集成

  • ⚡ 与 LangChain、n8n 或任何兼容 MCP 的客户端集成


📌 开发状态

本项目处于活跃开发阶段。 核心功能稳定(通过 MCP 工具和资源检索 ForexFactory 经济日历事件),但我们仍在:

  • 扩展功能(提示词、部署选项)

  • 改进文档和示例

我们欢迎在构建生态系统的过程中提供反馈和贡献。


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)

(查看仓库以获取完整详情 — 这是供贡献者参考的高层布局。)


Related MCP server: MCP Financial Data Gateway

🔧 安装

要求

  • Python 3.12+

  • uv 或 pip

  • 现代终端或兼容 MCP 的客户端

设置

# 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

▶️ 使用方法

⚡ 快速入门

使用默认设置(stdio 传输)启动服务器:

uv run ffcal-server

使用 HTTP 传输运行:

uv run ffcal-server --transport http --host 0.0.0.0 --port 8080

SSE 传输 (⚠️ 已弃用)

uv run ffcal-server --transport sse --host 127.0.0.1 --port 8001

环境变量默认值

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080

🏷️ 命名空间

默认命名空间:

ffcal

通过 .env 覆盖:

NAMESPACE=ffcal

📦 资源

名称

路径

描述

events_today

ffcal://events/today

今日事件

events_week

ffcal://events/week

本周所有事件

events_range

ffcal://events/range/{start}/{end}

自定义日期范围


🛠️ 工具

名称

类型

描述

ffcal_get_calendar_events

工具

检索指定期间的事件

支持的值:

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

📝 提示词

名称

描述

ffcal_daily_prep

今日交易准备笔记

ffcal_weekly_outlook

每周宏观事件摘要

ffcal_volatility_grid

每周事件风险热力图

ffcal_trade_map_scenarios

特定事件的情景映射


🧩 提示词风格

所有提示词均支持 style 参数以控制格式。 默认:

style: str = "bullet points"

请参阅 输出风格参考 获取可用格式。


💻 客户端示例

示例:使用 MCP CLI

mcp call ffcal:get_calendar_events time_period=this_week

示例:在 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)

示例:LangChain 集成

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)

📘 客户端配置参考

📖 docs/CLIENT_CONFIG_REFERENCE.md

包括:

  • ✅ Claude Desktop (本地 + Docker) 的示例配置

  • 🐳 Docker 构建和设置

  • 🧩 VS Code MCP 集成(未来)

  • 🧪 测试 + 故障排除清单

  • 🔍 用于可视化调试的 Inspector 设置


⚙️ 配置

变量

默认值

描述

NAMESPACE

ffcal

命名空间前缀

MCP_TRANSPORT

stdio

传输类型 (stdio, http, sse)

MCP_HOST

127.0.0.1

HTTP/SSE 主机

MCP_PORT

8000

HTTP/SSE 端口

SCRAPER_TIMEOUT_MS

5000

Playwright 超时时间

LOCAL_TIMEZONE

系统本地

时区覆盖


示例 .env

MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8080
NAMESPACE=ffcal

🐳 Docker 集成

支持 stdio(默认)和 HTTP/SSE。

docker compose build
docker compose up forexfactory_mcp

运行 MCP 服务器并将其暴露在 8000 端口。


目标

描述

make build

构建 Docker 镜像

make run-http

以 HTTP 模式运行服务器

make run-stdio

以 stdio 模式运行

make dev-http

通过 MCP Inspector 检查

make stop

停止容器


🐍 1. uv 或依赖安装失败

运行:

docker compose build --no-cache forexfactory_mcp

⚡ 2. 服务器立即退出

切换到:

make run-http

🌐 3. 端口被占用

更改端口:

docker compose run --rm -e MCP_PORT=8080 forexfactory_mcp

🔐 4. 浏览器失败

安装 Chromium:

docker compose run forexfactory_mcp playwright install chromium

🧪 测试

pytest -v

📊 路线图

  • [ ] 按货币和影响程度筛选事件

  • [ ] 历史数据回填

  • [ ] MCP 提示词扩展

  • [ ] 云就绪部署


🤝 贡献

  1. Fork 本仓库

  2. 创建功能分支

  3. 使用清晰的消息提交

  4. 推送并开启 PR


📜 许可证

MIT 许可证 – 详情请参阅 LICENSE。

Available Tools

1 tool
my-ffcal_get_calendar_eventsC

Retrieve ForexFactory calendar events for a given time period or custom date range.Valid time_period values include: today, tomorrow, yesterday, this_week, next_week, last_week, this_month, next_month, last_month, custom.

Inputs: time_period, start_date, end_date. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool has a clear and distinct purpose: retrieving ForexFactory calendar events.

    Naming Consistency5/5

    Since there is only one tool, naming consistency is inherently perfect. The tool name 'my-ffcal_get_calendar_events' follows a verb_noun pattern, which is consistent with itself.

    Tool Count2/5

    A single tool is generally too few for a server's purpose, as it limits functionality and scope. For a ForexFactory calendar server, one might expect additional tools for filtering, sorting, or managing events, making this count feel thin and under-scoped.

    Completeness2/5

    The server only provides retrieval of calendar events, with no tools for creating, updating, deleting, or otherwise managing events. This is a significant gap, as it lacks basic CRUD operations and limits the server's utility to read-only access.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 10 financial data tools (market data, economic indicators, news, insider trades, and calendars) via a single MCP layer, enabling any MCP-compatible LLM to access diverse financial data through a unified interface.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides macro-economic event data, earnings reports, and market overviews as MCP tools, enabling AI agents to query calendars, check event proximity, and assess trade safety.
      57 PyPI
      2
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to access and analyze Forex Factory economic calendar data, including enriched event details and summary statistics, through MCP tools and resources.
      -