FinanceMarker MCP Server

MCP‑сервер для интеграции FinanceMarker.ru с LLM‑агентами, IDE (MCP), n8n и другими MCP‑совместимыми клиентами. Сервер проксирует REST API FinanceMarker и предоставляет его как набор MCP tools.

Возможности

• Полное покрытие API по спецификации FinanceMarkerAPI.json
• Кэширование ответов на 24 часа (SQLite через @keyv/sqlite)
• Стабильные ключи кэша (метод+путь+параметры), исключение из кэша /fm/v2/token_info
• Русскоязычные описания параметров tools (zod.describe())

Требования

• Node.js 18+
• Токен FinanceMarker (FINANCEMARKER_API_TOKEN)

Быстрый старт (npx)

npx --package=@ru-financial-tools/financemarker-mcp financemarker-mcp

Настройка в Cursor (рекомендуется «сырые» значения)

Переменные окружения в mcp.json лучше указывать «сырыми» значениями, без подстановок ${VAR}.

{
  "mcpServers": {
    "financemarker-mcp": {
      "command": "npx",
      "args": ["-y", "--package=@ru-financial-tools/financemarker-mcp", "financemarker-mcp"],
      "env": {
        "FINANCEMARKER_API_TOKEN": "<ваш_токен>",
        "FINANCEMARKER_BASE_URL": "https://financemarker.ru/api",
        "FINANCEMARKER_LOG_LEVEL": "info",
        "FINANCEMARKER_CACHE_TTL_MS": "86400000"
      }
    }
  }
}

Альтернатива: локальная разработка

Если запускаете сервер локально из исходников:

{
  "mcpServers": {
    "financemarker-mcp": {
      "command": "node",
      "args": ["dist/cli.js"],
      "env": {
        "FINANCEMARKER_API_TOKEN": "<ваш_токен>",
        "FINANCEMARKER_BASE_URL": "https://financemarker.ru/api",
        "FINANCEMARKER_LOG_LEVEL": "debug",
        "FINANCEMARKER_CACHE_TTL_MS": "86400000"
      }
    }
  }
}

Переменные окружения

• FINANCEMARKER_API_TOKEN — токен доступа (обязательно)
• FINANCEMARKER_BASE_URL — опционально, базовый URL API
• FINANCEMARKER_CACHE_TTL_MS — опционально, TTL кэша по умолчанию

Скрипты

npm run build       # сборка (tsup)
npm run typecheck   # проверка типов (tsc)
npm test            # тесты (vitest)

или через Makefile:

make ci   # install+typecheck+test+build

Мэппинг API → MCP tools

Поддерживаются инструменты для: token_info, exchanges, calendar, disclosure, dividends, experts, ideas, ideas/{id}, insider_transactions, operation_metrics, stocks, stocks/{exchange}:{code}. Все входные параметры описаны через zod.

Безопасность

Токен FINANCEMARKER_API_TOKEN храните в приватных секретах CI/CD и не коммитьте в репозиторий.

Лицензия

MIT — см. файл LICENSE.