ak-mcp: Servidor MCP de datos financieros AKShare

ak-mcp es un servicio de consulta de datos financieros basado en el Model Context Protocol (MCP), que utiliza AKShare como fuente de datos y registra automáticamente los más de 1000 interfaces de datos incluidos en el diccionario de datos oficial como herramientas MCP, para que agentes como Claude, Codex y Cursor puedan descubrirlas y llamarlas directamente. Los resultados de las consultas se escriben por defecto en la caché local de MySQL; cuando la caché acierta, no se accede a la fuente de datos remota, lo que reduce significativamente la dependencia de la red y la latencia.

Características

• Cumple con el protocolo MCP más reciente: basado en el SDK oficial de Python v2 (mcp>=2.0), implementa el protocolo revisado de 2026-07-28 y es automáticamente compatible con clientes de 2025-11-25 y versiones anteriores; el mismo servicio admite simultáneamente dos transportes: stdio y Streamable HTTP.

• Cobertura completa de interfaces: la lista de interfaces se genera directamente a partir de la documentación oficial (https://akshare.akfamily.xyz/data/); actualmente incluye 1019 interfaces, que cubren todas las categorías principales: acciones, futuros, bonos, opciones, divisas, dinero, mercado al contado, tasas de interés, fondos privados/públicos, índices, macroeconomía, criptomonedas, banca, energía, datos alternativos, caja de herramientas, cálculo de indicadores, etc.

• Prioridad de caché: si la caché de MySQL acierta, se devuelve directamente; si no acierta, se consulta la fuente original de AKShare y se escribe en la caché; si la consulta a la fuente falla, se devuelven automáticamente los datos caducados marcados con stale: true.

• TTL por categoría: las cotizaciones en tiempo real, el historial de frecuencia diaria, los indicadores macroeconómicos y los diccionarios estáticos utilizan diferentes períodos de validez de caché, con soporte para sobrescribir por función.

• Esquema de parámetros nativo: los parámetros de cada herramienta se generan automáticamente a partir de la firma de la función de AKShare (obligatorio/opcional, tipo, valor predeterminado); el agente puede llamarlos directamente según los parámetros de la documentación, sin necesidad de aprender formatos de encapsulación adicionales.

• Fácil de operar: incluye herramientas meta integradas como búsqueda de interfaces, estadísticas de caché, limpieza de caché, verificación de salud y consulta directa sin pasar por la caché.

Arquitectura

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/>检索 / 统计 / 清理 / 健康]

Estructura de directorios

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

Requisitos del entorno

• Python 3.11+ (se recomienda 3.11/3.12/3.13)

• MySQL 8.0+ (se puede usar el Docker Compose incluido en el proyecto)

• AKShare requiere oficialmente un sistema operativo de 64 bits

Inicio rápido

1. Instalación

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

2. Iniciar MySQL

Opción 1 (recomendada): usar el Docker Compose incluido en el proyecto:

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

Opción 2: usar un MySQL existente y ejecutar la inicialización manualmente:

mysql -uroot -p < scripts/init_db.sql

3. Configuración

cp .env.example .env

Modifique .env según sea necesario. La configuración predeterminada corresponde al contenedor MySQL incluido en el proyecto:

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

Todos los elementos de configuración se encuentran en .env.example.

4. Generar la lista de interfaces (opcional)

El repositorio ya incluye config/akshare_registry.json (correspondiente a la documentación oficial 1.18.94); normalmente no es necesario regenerarlo. Para sincronizar con la documentación más reciente:

make registry

5. Iniciar el servicio

Modo stdio (para que los clientes de escritorio lo llamen localmente):

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

Modo Streamable HTTP (para llamadas remotas/multicliente):

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

Otros comandos:

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

Inicio rápido: integración con agentes

Claude Desktop

Edite claude_desktop_config.json (la configuración MCP de 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"
      }
    }
  }
}

Después de guardar, reinicie Claude Desktop y podrá usar directamente en la conversación todas las herramientas de datos como stock_zh_a_hist, fund_open_fund_info_em, macro_china_cpi_yearly, etc.

Codex

Agregue lo siguiente en ~/.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" }

También puede usar el comando de adición MCP de Codex CLI (la sintaxis exacta depende de la versión actual de Codex: codex mcp --help).

Cliente MCP genérico (HTTP)

Primero inicie el modo HTTP:

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

Luego configure en el cliente MCP que admita URL:

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

Ejemplos de uso

Consultar el historial de cotizaciones de acciones A

El agente llama directamente a la herramienta stock_zh_a_hist, con parámetros idénticos a los de la documentación oficial de AKShare:

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

Devuelve 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
  }
}

Localizar interfaces

Si no está seguro del nombre de la interfaz, llame primero a ak_search_functions:

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

Herramientas meta de operación

Mecanismo de la lista de interfaces

1. scripts/build_registry.py obtiene los archivos fuente Markdown de todas las páginas del directorio data/ de la documentación oficial, analiza 接口：xxx (Interfaz: xxx), 描述：xxx (Descripción: xxx) y la tabla de parámetros de entrada, y genera config/akshare_registry.json.

2. Al iniciar el servicio, esta lista es la única fuente: las interfaces incluidas en la lista y presentes en el akshare instalado se registran una a una como herramientas MCP.

3. Las interfaces que están en la lista pero faltan en el paquete instalado se omiten con una advertencia (por ejemplo, cuando la documentación se publica antes que la versión); se puede usar AKSHARE_REQUIRE_VERSION_MATCH=true para forzar la coincidencia de versiones.

Mecanismo de caché

Flujo de prioridad de caché

1. Se calcula una clave de caché SHA-256 basada en nombre de función + parámetros normalizados + versión de akshare.

2. Si acierta y no ha caducado: devuelve directamente el JSON de la caché (meta.cached = true).

3. Si no acierta o ha caducado: llama a AKShare para obtener la fuente original, la normaliza y la escribe en MySQL.

4. Si la consulta a la fuente falla: si existen datos caducados, devuelve los datos antiguos marcados con meta.stale = true; de lo contrario, devuelve el texto de error.

Estructura de la tabla (ak_cache)

Al iniciar el servicio, la tabla se crea automáticamente mediante SQLAlchemy; también puede consultar scripts/init_db.sql para crearla manualmente:

Reglas TTL

Las reglas se definen en config/ttl_rules.yaml, se comparan en orden y la primera coincidencia es la que se aplica:

Elementos de configuración

Desarrollo y pruebas

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

Cobertura de pruebas: análisis de documentación, generación de esquemas, clasificación TTL, normalización de parámetros, claves de caché, comportamiento de caché SQLite, registro/llamada/manejo de errores de herramientas en modo MCP en memoria. La verificación de integración con red real y MySQL se puede ejecutar manualmente mediante Docker Compose local (consulte la "Verificación de extremo a extremo" anterior).

Preguntas frecuentes

Al iniciar, se indica que una interfaz no se encuentra: Registry function not found in installed akshare: xxx significa que la documentación oficial se publicó antes que la versión actualmente instalada de akshare; esa interfaz se omitirá sin afectar a las demás. Actualice akshare o regenere la lista.

Error de conexión a MySQL: verifique que el puerto en .env coincida con el que muestra docker compose ps (el contenedor de este proyecto mapea directamente el puerto estándar 3306); también puede establecer AK_CACHE_ALLOW_DEGRADED=true para iniciar temporalmente en modo sin caché.

Error en la interfaz de la fuente de datos: algunas interfaces de AKShare dependen de sitios web de terceros (Sina, East Money, etc.) y pueden verse afectadas por la red, el control de riesgos o cambios en los campos; puede usar ak_execute_raw para reproducir el error sin pasar por la caché, o actualizar la versión de akshare.

Zona horaria y codificación: el tiempo de caché se unifica en UTC; los datos se escriben y leen con UTF-8/utf8mb4, y los nombres de columnas en chino se pueden devolver directamente.

Recomendaciones de seguridad y producción

• v1 está orientado a uso local y de intranet, sin autenticación ni limitación de velocidad integradas; en producción se recomienda colocarlo detrás de una puerta de enlace (OAuth/API Key, límite de velocidad).

• La caché es compartida por todos los agentes, sin distinción de usuarios; para escenarios sensibles, agregue su propio aislamiento.

• Cuando el modo HTTP se expone externamente, se recomienda escuchar solo en la dirección de la intranet o agregar TLS mediante un proxy inverso.

Licencia

MIT