AKBridge

AKBridge 将 AKShare 公共接口自动接入 MCP。

简体中文 | English

安装 | 客户端配置 | 调用示例

AKBridge 0.2.0 破坏性变更：默认工具面从 all 改为 router，已依赖默认模式的客户端需显式传 --mode all。同版本支持 structured content、MCP Prompts、按需文档资源和 Streamable HTTP；旧版 SSE 仍保留并标记为 deprecated。

将 AKShare 公共接口自动暴露为 MCP 工具，并提供路由检索、结构化输出、逐接口验收以及自动化验收与维护。当前 AKShare 基线版本、接口数量和验收结果见中文验收汇总与English acceptance summary。

为什么选择 AKBridge

AKShare 覆盖广泛的金融数据接口，但直接接入 AI 助手仍需处理 Python 调用、函数选择、参数构造、DataFrame 转换和版本变化。AKBridge 把这些工作收敛为一个可安装、可检索、可验收的 MCP 服务，适合构建金融研究助手、行情分析 Agent 或数据检索工具：

• 覆盖 AKShare 完整公共接口，而不是长期手工维护少量工具；
• 只向 LLM 暴露三个稳定的路由工具，降低上千个接口带来的上下文压力；
• 提供统一的 JSON 输出、分页、摘要和错误分类，而不是直接处理不同形态的 Python 返回值；
• 在 AKShare 更新后自动发现接口变化，并通过逐接口验收判断是否仍可安全使用。

AKBridge 不替代 AKShare：AKShare 负责数据获取，AKBridge 负责把这些能力可靠地交给 MCP 客户端、Agent 或其他工具。第三方数据源自身的登录、验证码、反爬、限流和网络限制仍然存在，并会被单独报告。

验收状态

状态图由验收报告命令自动生成，详细结果见中文验收汇总、English acceptance summary和逐接口明细。

GitHub Actions 与 Dependabot 自动检查 AKShare 与 mcp 更新：AKShare 的同主版本升级与 mcp 的同主版本 patch 升级在完整验收通过后自动合并，依赖固定版本变化还会自动发布新版本。频率、门禁与仓库配置见自动化验收与维护说明。

功能

• 自动发现 AKShare 公共可调用接口，按函数签名生成 MCP 输入 Schema，无需手工维护上千个适配器。
• 支持 DataFrame、Series、日期和常见 NumPy 标量的 JSON 转换，以及 DataFrame JSON 入参与时间索引转换。
• 提供逐接口隔离验收、超时控制、并发执行、验收参数集和断点续跑。
• 生成逐接口 CSV 明细以及 JSON、Markdown 汇总报告。
• 提供本地语义目录、确定性检索和三工具路由模式。
• 支持 raw、compact、summary 三种输出模式、分页、字段类型和单位提示。
• 提供重试、限速、缓存、熔断、代理配置、敏感信息脱敏以及自动化验收与维护门禁。

安装

推荐使用 uv 安装命令行工具，它会为 AKBridge 管理隔离的 Python 3.11+ 环境。普通用户从 PyPI 安装最新发布版：

uv tool install akbridge

uv tool update-shell

重新打开终端后验证：

akbridge --help

akbridge --mode router

第二条命令启动 stdio MCP 服务并等待客户端连接，终端看起来没有输出是正常现象，可按 Ctrl+C 停止。安装默认分支的开发版本用 uv tool install --force "git+https://github.com/kevynf/akshare-mcp-bridge.git"；升级和卸载分别是 uv tool upgrade akbridge 与 uv tool uninstall akbridge。

参与开发或需要修改代码时才克隆仓库：

git clone https://github.com/kevynf/akshare-mcp-bridge.git

cd akbridge uv sync --group dev uv run --no-sync akbridge --mode router

stdio 服务启动后不会显示网页、菜单或命令提示符，MCP 客户端通过标准输入输出与该进程通信。

两种工具模式

router 是默认模式（自 0.2.0 起），只公布三个稳定工具，是连接 LLM 的推荐方式。all 模式保留所有已发现的 AKShare 原始函数工具，适合兼容已有客户端、逐接口验收和人工精确调用，但超过 50 个接口时会在 stderr 给出提示。hybrid 模式同时暴露两套接口，主要用于迁移与调试。

akbridge              # 默认即 router 模式

akbridge --mode all # 显式选择完整工具面

检索器从 AKShare 公开函数自动生成 一级分类 → 源码模块 → 接口 路由树，例如 stock → stock_feature.stock_hist_em → stock_zh_a_hist。函数名、签名、别名和 docstring 构成默认的确定性词法证据，不调用 LLM、嵌入服务或远程向量数据库。MCP 资源 akbridge://skill 提供同一套运行时调用规程，它随服务暴露，不会自动安装成客户端 Skill。

自 0.2.0 起，三个 router 工具都声明了 outputSchema，并以 structuredContent 形式返回结构化结果，便于 MCP 客户端零成本消费；同时保留 TextContent JSON 文本作为向后兼容的回退。工具描述头部带有人类可读的 title（"AKBridge Search" 等）和 _meta.documentation_uri 指向 README。

AKShare 文档词法路由

正式发布的 wheel 和 sdist 会在 GitHub Actions 中，根据固定的 AKShare 版本解析对应的版本标签（新版 vX.Y.Z 或旧版 release-vX.Y.Z）和 commit SHA，自动构建并包含文档索引；router 模式默认加载包内索引，服务搜索期间不会联网。文档块只关联 AKShare 顶层公开函数，补充自然语言术语和排序证据，不决定领域或模块结构；搜索结果会返回命中的文档标题和来源链接。

自 0.2.0 起，AKBridge 通过 MCP ResourceTemplate 发布文档资源模板；akbridge_search 命中时，documentation 数组会附带具体的 uri，客户端可用 resources/read 读取完整文档，无需访问外部 URL。没有加载文档索引时，模板仍可见，但搜索结果不会返回具体文档 URI。

源码开发时可手动重建或覆盖索引：

akbridge-docs build --ref <akshare-commit-sha> --output artifacts\akshare-docs.json

akbridge --mode router --document-index artifacts\akshare-docs.json

客户端配置

选择使用的 MCP 客户端，跳转到对应配置：Cherry Studio、Codex或其他客户端。

Cherry Studio

Cherry Studio 可以通过 stdio 直接启动 AKBridge，不需要额外的适配服务，推荐使用 router 模式。

协议安装：将下面的地址复制到浏览器地址栏或 Windows“运行”窗口，打开 Cherry Studio 后检查安装预览并确认。如果没有打开自定义协议，请改用下方的 JSON 导入。

cherrystudio://mcp/install?servers=eyJtY3BTZXJ2ZXJzIjp7ImFrYnJpZGdlIjp7InR5cGUiOiJzdGRpbyIsImNvbW1hbmQiOiJ1dngiLCJhcmdzIjpbImFrYnJpZGdlIiwiLS1tb2RlIiwicm91dGVyIl19fX0%3D

Cherry Studio 会以未启用、未信任状态导入配置，仍需由用户确认并启用。

从 JSON 导入：打开 设置 → MCP → MCP 服务器 → 添加 → 从 JSON 导入，粘贴：

{

"mcpServers": { "akbridge": { "type": "stdio", "command": "uvx", "args": ["akbridge", "--mode", "router"] } } }

启用服务并确认状态正常后，将 AKBridge 绑定到需要使用它的 Agent。首次启动时 uvx 可能需要下载并创建运行环境，会比后续启动更慢。

Codex 配置

在 Codex MCP 配置中加入：

[mcp_servers.akbridge]

command = "akbridge" args = ["--mode", "router"] startup_timeout_sec = 30 tool_timeout_sec = 120

保存配置并重启 Codex，客户端初始化成功后即可看到 AKShare 工具。

其他 MCP 客户端

支持 JSON MCP 配置的客户端（Claude Desktop 及兼容客户端）可以使用：

{

"mcpServers": { "akbridge": { "command": "akbridge", "args": ["--mode", "router"] } } }

调用示例

连接 MCP 服务后，用户可以直接描述数据需求，无需预先知道 AKShare 函数名：

查询股票代码 000001 从 2026-01-01 到 2026-08-06 的前复权日线行情。

类似的自然语言请求还有“获取 A 股实时行情”“查询中国 CPI 数据”“获取开放式基金净值”“查询国内期货实时行情”。MCP 客户端中的 LLM 负责把需求转换为下方的检索、描述和结构化调用；AKBridge 本身不使用 LLM，每个工具的参数来自对应 AKShare 函数签名，具体含义以工具描述和 AKShare 文档为准。

路由调用与结果格式

典型顺序是先检索、再描述、最后调用：

{"query": "A股历史行情", "limit": 5}

{"name": "stock_zh_a_hist"}

{

"name": "stock_zh_a_hist", "arguments": { "symbol": "000001", "period": "daily", "start_date": "20260101", "end_date": "20260806", "adjust": "qfq" }, "output_mode": "compact", "page": 1, "page_size": 100 }

字段和单位提示由结果列名和 dtype 自动推断，属于辅助元数据，不替代 AKShare 或数据源的正式定义。

指标与可观测性

akbridge_call 默认 不 在响应里附带 metrics 快照，避免 by_api 累积表让每次响应变大。需要时显式传 include_metrics: true，或读取 akbridge://metrics 资源拿到全量计数器：

{"name": "stock_zh_a_hist", "arguments": {...}, "include_metrics": true}

akbridge_call 的 annotation 标记为 open-world 和 state-changing；客户端是否展示这些 annotation 取决于客户端实现。副作用接口的授权门禁还会由服务端强制执行。

结构化错误响应

所有工具错误都以 isError=true 返回，错误正文是 JSON 文档，包含稳定的 error.code 以及 LLM 恢复建议：

{

"error": { "code": "UNKNOWN_API", "message": "Unknown AKShare API: foo", "suggestions": ["stock_zh_a_hist", "..."], "retry_hint": "Use akbridge_search to find candidates, then akbridge_describe to confirm the canonical name and schema." } }

错误码枚举：UNKNOWN_API、TOOL_NOT_AVAILABLE、SCHEMA_VIOLATION、INVALID_ARGUMENT、UPSTREAM_TIMEOUT、UPSTREAM_ERROR、CIRCUIT_OPEN、RATE_LIMITED、SIDE_EFFECT_DENIED、UNKNOWN_RESOURCE、UNKNOWN_PROMPT、INTERNAL_ERROR。LLM 客户端可以基于 code 选择检索备用接口、放慢调用频率或放弃。

副作用接口

以 set_*、login、logout、configure 开头或名字含 token/secret/password/api_key/cookie 的接口被标记为副作用接口。无论客户端是否处理 annotations，AKBridge 都会在服务端拒绝缺少 allow_side_effect=true 的调用；这个参数仅表示上层已完成授权确认，AKBridge 不会自行显示确认框：

• ToolAnnotations.readOnlyHint=false、destructiveHint=true、idempotentHint=false
• 工具描述头部加 ⚠️ SIDE EFFECT: 警告前缀
• _meta.x-requires-confirmation=true，为支持该约定的 MCP 客户端提供授权提示
• 不参与缓存和自动重试

MCP Prompts

自 0.2.0 起，AKBridge 暴露三个协议层 MCP prompts，对应常见工作流：

支持 MCP Prompts 的客户端可以从 Prompt 菜单选择对应流程；具体触发 UI 由客户端决定。

DataFrame 入参

少数计算接口需要 pandas.DataFrame，MCP 客户端可以传入记录数组：

{

"data": { "index_column": "date", "rows": [ {"date": "2026-01-05T09:30:00", "Open": 10.0, "High": 10.3, "Low": 9.9, "Close": 10.2} ] } }

index_column 指定转换为 DataFrame 索引的列，ISO 日期字符串会自动转换为 DatetimeIndex。

逐接口验收

接口清单由发现机制自动生成，记录 AKShare 版本、接口总数、函数签名、输入 Schema 哈希以及自动生成的显示名、类别、别名、用途、示例、返回元数据、副作用标记和数据源链接，落在 artifacts/acceptance/manifest.json；artifacts/catalog.json 是同一目录的紧凑 RAG 导出。常用命令：

.venv\Scripts\python.exe -m akbridge.acceptance manifest

.venv\Scripts\python.exe -m akbridge.acceptance run --limit 20 --timeout 30 --workers 4 .venv\Scripts\python.exe -m akbridge.acceptance run --resume --retry-status timeout --timeout 60

--limit 控制本次验收数量，--resume 继续上次进度，--retry-status timeout 复验超时接口，--name 只验收指定接口；必填验收参数位于 artifacts/acceptance/fixtures.json。完整参数与断点续跑细节见自动化验收与维护说明。

验收状态取值

MCP 适配验收与数据源可用性分开统计：只要接口已被发现、生成 Schema，并成功进入 AKShare 调用路径且没有 fixture_required 或 worker_failed，就视为 MCP 适配通过。上游失败不会被隐藏或伪装成成功。

生成报告

.venv\Scripts\python.exe -m akbridge.acceptance report

报告写入 artifacts/acceptance/ 下的 SUMMARY.md/SUMMARY.en.md（双语汇总）、summary.json（机器可读）、status.svg（README 状态图）、ledger.csv（逐项结果）和 manifest.json（完整清单）。当前基线的精确版本、接口数量和各状态统计见验收汇总，失败范围分为上游网络、上游响应、AKShare 运行错误和上游超时，详细原因见逐接口明细。报告由验收命令生成，升级 AKShare 时无需手工同步 README 中的数字。

自动化验收与维护

默认离线门禁不访问第三方数据源，也不需要人或 LLM：

.venv\Scripts\python.exe -m akbridge.maintenance ci --strict `

--baseline artifacts\acceptance\manifest.json --current artifacts\maintenance\manifest.json --catalog artifacts\catalog.json ` --report artifacts\maintenance\latest.json

它会重新发现全部接口、构造并验证全部 all 工具和固定的 3 个 router 工具、验证输入 Schema 和 router 索引、生成语义目录、比较接口新增/删除/签名/Schema 差异，并在接口删除或签名/Schema 回归时返回非零退出码。定时任务可加 --check-latest 查询 PyPI 最新 AKShare 版本，网络不可用只记录为 unavailable，需要让发现新版本时任务失败再加 --fail-on-update。

只验证适配契约而不访问数据源：

.venv\Scripts\python.exe -m akbridge.acceptance run --offline --workers 4

全量数据源验收反映上游网站、验证码、登录和限流状态，而不是 MCP 适配是否正确，应单独作为网络探测任务：

.venv\Scripts\python.exe -m akbridge.maintenance ci --provider --timeout 60 --workers 4

自动化维护工作流每周运行离线流程并上传报告，数据源探测工作流每月 1 日和 15 日各执行一次全量隔离验收。完整规则见[自动化验收与维护说明](docs/automated-validation-and-main