Ak Share MCP

AKShareMCP

一个面向量化开发者的「元数据驱动（Metadata-Driven）」AKShare 万能 MCP 工具：

• 离线层：抓取 AKShare 文档，生成 akshare_api_specs.json
• 服务层：FastMCP + 反射转发器（getattr(akshare, api_name)(**params)）
• 客户端：在 Cherry Studio / Codex 里先查字典再执行，避免“幻觉参数”

设计理念

• 解耦：接口定义（Schema）与代码实现（Implementation）完全分离，文档变化只需更新 specs 文件。
• 反射：通过动态转发 getattr(akshare, api_name)(**params) 替代上百个静态函数。
• 认知闭环：在客户端 SOP 中强制“先查字典再执行”，避免幻觉参数。

架构概览

1) 离线层（Cartographer）：抓取 AKShare 文档，生成 akshare_api_specs.json 2) 服务层（Universal Gateway）：FastMCP + 反射 + 风控（限流/截断/异常处理） 3) 客户端（Cognitive Agent）：严格按“查字典 -> 构参 -> 执行 -> 解释”流程

1) 安装

建议使用虚拟环境：

python -m venv .venv
. .venv/bin/activate
pip install -U pip
pip install -e ".[scrape]"

2) 离线构建数据字典（Scraper）

生成 data/akshare_api_specs.json：

akshare-mcp-scrape --base-url https://akshare.akfamily.xyz/data/index.html --output data/akshare_api_specs.json

3) 运行万能 MCP Server（Stdio）

akshare-mcp-server --specs data/akshare_api_specs.json

Docker 运行

方式 A：直接 Docker

docker build -t akshare-mcp .
docker run --rm -i -v "$PWD/data:/app/data" akshare-mcp

MCP 使用 stdio，务必加 -i 保持标准输入。

方式 B：Docker Compose

docker compose up --build

MCP 客户端配置示例（通过 docker）：

{
  "mcpServers": {
    "akshare": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "./data:/app/data", "akshare-mcp"]
    }
  }
}

Scraper（Docker）

构建并运行离线文档爬虫（生成 data/akshare_api_specs.json）：

docker build -f Dockerfile.scraper -t akshare-mcp-scraper .
docker run --rm -v "$PWD/data:/app/data" akshare-mcp-scraper

使用 Compose：

docker compose run --rm akshare-scraper

HTTP / WS 网关

如果需要远程调用 MCP，可启动 HTTP/WS 网关（默认端口 8787）。

本机启动

akshare-mcp-gateway --specs data/akshare_api_specs.json --host 0.0.0.0 --port 8787

Docker 启动

docker compose up -d akshare-gateway

HTTP 端点

• MCP HTTP 端点：/mcp（streamable-http）
• 健康检查：/healthz

WebSocket 端点（MCP 标准）

/ws 使用 MCP WebSocket 传输（子协议 mcp），可用于支持 WS 的 MCP 客户端直连。

该 Server 仅暴露 2 个核心工具：

• search_api_docs(keyword, limit=10)：查字典（模糊搜索 + 返回参数/字段）
• execute_akshare_query(api_name, params)：万能执行（反射调用 + 自动截断）

MCP 客户端配置示例

见 examples/mcp_config.json。

4) 风控参数（可选）

• AKSHARE_MCP_MAX_ROWS：返回行数截断（默认无限制；<=0 或不设表示不截断）
• AKSHARE_MCP_MIN_INTERVAL_SECONDS：最小请求间隔（默认 0s）
• AKSHARE_MCP_SPECS_PATH：默认 specs 路径（默认 data/akshare_api_specs.json）

推荐 SOP（客户端）

1) search_api_docs 搜索接口与参数 2) 根据 required 构造参数 3) execute_akshare_query 执行 4) 若报错或缺参，回到第 1 步修正