ak-mcp: AKShare 金融数据 MCP Server

ak-mcp — это сервис запросов финансовых данных на основе Model Context Protocol (MCP), использующий AKShare в качестве источника данных. Он автоматически регистрирует более 1000 интерфейсов из официального словаря данных как инструменты MCP, чтобы агенты Claude, Codex, Cursor и другие могли напрямую обнаруживать и вызывать их. Результаты запросов по умолчанию записываются в локальный кэш MySQL; при попадании в кэш удалённый источник данных не запрашивается, что значительно снижает зависимость от сети и задержки.

Возможности

• Соответствие последней версии протокола MCP: на основе официального Python SDK v2 (mcp>=2.0) реализован протокол редакции 2026-07-28 с автоматической совместимостью с клиентами от 2025-11-25 и более ранних версий; один и тот же сервис одновременно поддерживает транспорты stdio и Streamable HTTP.

• Полное покрытие интерфейсов: список интерфейсов формируется непосредственно из официальной документации (https://akshare.akfamily.xyz/data/); в настоящее время включено 1019 интерфейсов, охватывающих все основные категории: акции, фьючерсы, облигации, опционы, валюты, денежный рынок, спот, процентные ставки, частные/публичные фонды, индексы, макроэкономика, криптовалюты, банки, энергетика, альтернативные данные, инструменты, расчёт показателей и др.

• Приоритет кэша: при попадании в кэш MySQL данные возвращаются сразу; при отсутствии — выполняется обращение к AKShare с записью в кэш; при сбое обращения автоматически возвращаются устаревшие данные с пометкой stale: true.

• TTL по категориям: для данных реального времени, дневной истории, макроэкономических показателей и статических справочников используются разные сроки действия кэша с поддержкой переопределения по функциям.

• Нативная схема параметров: параметры каждого инструмента автоматически генерируются из сигнатуры функции AKShare (обязательные/необязательные, типы, значения по умолчанию); агент может вызывать их напрямую по параметрам из документации без изучения дополнительных форматов обёртки.

• Удобство эксплуатации: встроенные мета-инструменты для поиска интерфейсов, статистики кэша, очистки кэша, проверки работоспособности, прямых запросов в обход кэша и др.

Архитектура

flowchart LR
    A[Agent 客户端<br/>Claude / Codex / Cursor] -->|stdio 或 Streamable HTTP| M[MCP Server<br/>mcp>=2, 2026-07-28]
    M --> T[1000+ 个数据工具<br/>工具名 = AKShare 函数名]
    T --> E[执行器<br/>超时 / 参数过滤 / 结果规范化]
    E --> C{MySQL 缓存<br/>ak_cache}
    C -->|命中且未过期| R[返回 JSON]
    C -->|未命中或过期| K[AKShare]
    K --> C
    K --> D[新浪 / 东财 / 交易所等数据源]
    M --> Meta[元工具<br/>检索 / 统计 / 清理 / 健康]

Структура каталогов

ak-mcp/
├── src/ak_mcp/               # 服务端核心代码
│   ├── server.py             # MCP 服务装配与工具注册
│   ├── registry.py           # 文档接口清单加载与安装包匹配
│   ├── schema.py             # 函数签名 -> JSON Schema
│   ├── executor.py           # 线程池调用、超时、参数过滤
│   ├── normalize.py          # DataFrame -> JSON 规范化
│   ├── cache.py              # MySQL 缓存（SQLAlchemy）
│   ├── ttl.py                # TTL 规则引擎
│   ├── config.py             # 环境变量配置
│   └── cli.py                # 命令行入口
├── scripts/
│   ├── build_registry.py     # 抓取官方文档生成接口清单
│   └── init_db.sql           # MySQL 初始化 SQL
├── config/
│   ├── akshare_registry.json # 官方文档接口清单（已生成，1019 个）
│   └── ttl_rules.yaml        # 缓存 TTL 规则
├── tests/                    # 单元与集成测试
├── docker-compose.yml        # MySQL 8 本地环境
├── pyproject.toml
└── Makefile

Требования к окружению

• Python 3.11+ (рекомендуется 3.11/3.12/3.13)

• MySQL 8.0+ (можно использовать Docker Compose из проекта)

• AKShare официально требует 64-битную операционную систему

Быстрый старт

1. Установка

make install          # 创建 .venv 并安装依赖（等价于 pip install -e ".[dev]"）

2. Запуск MySQL

Способ 1 (рекомендуется): использовать Docker Compose из проекта:

make mysql-up         # docker compose up -d mysql，映射标准 3306 端口

Способ 2: использовать существующий MySQL, выполнив инициализацию вручную:

mysql -uroot -p < scripts/init_db.sql

3. Конфигурация

cp .env.example .env

При необходимости измените .env. Конфигурация по умолчанию соответствует контейнеру MySQL из проекта:

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=ak_mcp
MYSQL_PASSWORD=ak_mcp_password
MYSQL_DB=ak_mcp

Все параметры конфигурации см. в .env.example.

4. Генерация списка интерфейсов (необязательно)

В репозиторий уже включён config/akshare_registry.json (соответствует официальной документации 1.18.94), обычно повторная генерация не требуется. Для синхронизации с последней документацией:

make registry

5. Запуск сервиса

Режим stdio (для локального вызова из десктопных клиентов):

ak-mcp
# 或 .venv/bin/ak-mcp

Режим Streamable HTTP (для удалённого/многоклиентского вызова):

ak-mcp --transport http --host 127.0.0.1 --port 8765

Прочие команды:

ak-mcp --list-functions          # 打印全部文档接口
ak-mcp --refresh-registry        # 重新抓取官方文档并更新清单
ak-mcp --verbose                 # 调试日志

QuickStart: подключение агентов

Claude Desktop

Отредактируйте claude_desktop_config.json (конфигурация MCP для Claude Desktop):

{
  "mcpServers": {
    "ak-mcp": {
      "command": "/absolute/path/to/ak-mcp/.venv/bin/ak-mcp",
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ak_mcp",
        "MYSQL_PASSWORD": "ak_mcp_password",
        "MYSQL_DB": "ak_mcp"
      }
    }
  }
}

После сохранения перезапустите Claude Desktop — все инструменты данных, такие как stock_zh_a_hist, fund_open_fund_info_em, macro_china_cpi_yearly, станут доступны непосредственно в диалоге.

Codex

Добавьте в ~/.codex/config.toml:

[mcp_servers.ak-mcp]
command = "/absolute/path/to/ak-mcp/.venv/bin/ak-mcp"
env = { MYSQL_HOST = "127.0.0.1", MYSQL_PORT = "3306", MYSQL_USER = "ak_mcp", MYSQL_PASSWORD = "ak_mcp_password", MYSQL_DB = "ak_mcp" }

Также можно использовать команду добавления MCP из Codex CLI (точный синтаксис уточняйте по codex mcp --help для текущей версии Codex).

Универсальный MCP-клиент (HTTP)

Сначала запустите HTTP-режим:

ak-mcp --transport http --host 127.0.0.1 --port 8765

Затем настройте в MCP-клиенте, поддерживающем URL:

{
  "mcpServers": {
    "ak-mcp": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Примеры использования

Запрос исторических котировок A-акций

Агент напрямую вызывает инструмент stock_zh_a_hist, параметры совпадают с официальной документацией AKShare:

stock_zh_a_hist(symbol="000001", period="daily", start_date="20260801", end_date="20260826", adjust="")

Возвращаемый JSON:

{
  "data": [
    {
      "日期": "2026-08-03",
      "开盘": 10.38,
      "收盘": 10.47,
      "最高": 10.59,
      "最低": 10.32,
      "成交量": 886273
    }
  ],
  "meta": {
    "function": "stock_zh_a_hist",
    "params": { "symbol": "000001", "period": "daily" },
    "cached": true,
    "stale": false,
    "rows": 18,
    "elapsed_ms": 2,
    "truncated": false
  }
}

Поиск интерфейса

Если имя интерфейса неизвестно, сначала вызовите ak_search_functions:

ak_search_functions(query="可转债 实时行情")
ak_search_functions(category="macro")

Операционные мета-инструменты

Механизм списка интерфейсов

1. scripts/build_registry.py загружает Markdown-исходники всех страниц из каталога data/ официальной документации, разбирает 接口：xxx, 描述：xxx и таблицы входных параметров, формируя config/akshare_registry.json.

2. При запуске сервиса этот список является единственным источником: интерфейсы, включённые в список и присутствующие в установленном akshare, по одному регистрируются как инструменты MCP.

3. Интерфейсы, присутствующие в списке, но отсутствующие в установленном пакете, пропускаются с предупреждением (например, когда документация выходит раньше версии); можно принудительно требовать совпадения версий через AKSHARE_REQUIRE_VERSION_MATCH=true.

Механизм кэширования

Процесс с приоритетом кэша

1. Ключ кэша SHA-256 вычисляется по имя функции + нормализованные параметры + версия akshare.

2. Попадание и не истёк срок: возвращается кэшированный JSON напрямую (meta.cached = true).

3. Нет попадания или истёк срок: вызывается AKShare, результат нормализуется и записывается в MySQL.

4. Сбой обращения: если есть устаревшие данные, возвращаются старые данные с пометкой meta.stale = true; иначе возвращается текст ошибки.

Структура таблицы (ak_cache)

При запуске сервиса таблица создаётся автоматически через SQLAlchemy; также можно создать вручную по scripts/init_db.sql:

Правила TTL

Правила заданы в config/ttl_rules.yaml, сопоставляются по порядку, срабатывает первое совпадение:

Параметры конфигурации

Разработка и тестирование

make test          # 运行全部测试（单元 + MCP 内存集成）
make lint          # ruff 检查
make fmt           # ruff 格式化

Тесты покрывают: разбор документации, генерацию схем, классификацию TTL, нормализацию параметров, ключи кэша, поведение кэша SQLite, регистрацию/вызов/обработку ошибок инструментов в режиме MCP in-memory. Интеграционную проверку с реальной сетью и MySQL можно выполнить вручную через локальный Docker Compose (см. выше «Сквозная проверка»).

Частые вопросы

При запуске сообщается, что интерфейс не найден: Registry function not found in installed akshare: xxx означает, что официальная документация вышла раньше установленной версии akshare; этот интерфейс будет пропущен, на остальные это не влияет. Обновите akshare или перегенерируйте список.

Ошибка подключения к MySQL: проверьте, что порт в .env совпадает с выводом docker compose ps (контейнер проекта напрямую пробрасывает стандартный порт 3306); также можно временно запуститься без кэша, установив AK_CACHE_ALLOW_DEGRADED=true.

Ошибки интерфейсов источника данных: часть интерфейсов AKShare зависит от сторонних сайтов (Sina, East Money и др.) и может затрагиваться сетью, защитой от ботов или изменениями полей; можно воспроизвести через ak_execute_raw в обход кэша или обновить версию akshare.

Часовой пояс и кодировка: время кэша единообразно в UTC; запись и чтение данных — UTF-8/utf8mb4, китайские имена столбцов возвращаются напрямую.

Рекомендации по безопасности и продакшену

• v1 ориентирован на локальное использование и внутреннюю сеть, без встроенной аутентификации и ограничения частоты запросов; в продакшене рекомендуется размещать за шлюзом (OAuth/API Key, rate limiting).

• Кэш общий для всех агентов, без разделения по пользователям; при чувствительных сценариях добавьте собственную изоляцию.

• При внешнем доступе через HTTP-режим рекомендуется слушать только внутренний адрес или добавить TLS через обратный прокси.

License

MIT