📅 ForexFactory MCP Server

Сервер MCP (Model Context Protocol), который предоставляет данные экономического календаря ForexFactory в качестве ресурсов и инструментов.

Разработан для использования в агентских рабочих процессах, LLM и торговых помощниках.

• 📅 ForexFactory MCP Server

  • 🚀 Функции

    • 📌 Статус разработки

  • 🔧 Установка

    • Требования

    • Настройка

  • ▶️ Использование

    • ⚡ Быстрый старт

    • Транспорт SSE (⚠️ устарело)

    • Значения переменных окружения по умолчанию

  • 🏷️ Пространство имен

  • 📦 Ресурсы

  • 🛠️ Инструменты

  • 📝 Промпты

    • 🧩 Стили промптов

  • 💻 Примеры клиентов

    • Пример: Использование MCP CLI

    • Пример: Использование в Python

    • Пример: Интеграция с LangChain

    • 📘 Справочник конфигурации клиента

  • ⚙️ Конфигурация

    • Пример .env

  • 🐳 Интеграция с Docker

    • 🐍 1. Ошибка установки uv или зависимостей

    • ⚡ 2. Сервер немедленно завершает работу

    • 🌐 3. Порт занят

    • 🔐 4. Ошибка браузера

  • 🧪 Тестирование

  • 📊 Дорожная карта

  • 🤝 Участие в разработке

  • 📜 Лицензия

🚀 Функции

• ✅ Получение событий экономического календаря по периодам времени (today, this_week, custom и т.д.)

• ✅ Доступ через ресурсы MCP (для доступа по подписке)

• ✅ Доступ через инструменты MCP (прямые вызовы от клиентов/агентов)

• ✅ Ответы в формате JSON для легкой интеграции

• ⚡ Интеграция с LangChain, n8n или любым MCP-совместимым клиентом

📌 Статус разработки

Этот проект активно развивается. Основная функциональность стабильна (получение событий экономического календаря ForexFactory через инструменты и ресурсы MCP), но мы все еще:

• Расширяем возможности (промпты, варианты развертывания)

• Улучшаем документацию и примеры

Мы приветствуем отзывы и участие в разработке, пока продолжаем развивать экосистему.

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: Google-Calendar Universal MCP

🔧 Установка

Требования

• 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

📦 Ресурсы

🛠️ Инструменты

Поддерживаемые значения:

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

📝 Промпты

🧩 Стили промптов

Все промпты поддерживают параметр 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 (в будущем)

• 🧪 Чек-лист тестирования и устранения неполадок

• 🔍 Настройка инспектора для визуальной отладки

⚙️ Конфигурация

Пример .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.

🐍 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. Сделайте форк репозитория

2. Создайте ветку для функции

3. Закоммитьте с понятным сообщением

4. Отправьте изменения и откройте PR

📜 Лицензия

Лицензия MIT – подробности см. в LICENSE.