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

将 AKShare 公共接口自动暴露为 MCP 工具，并提供路由检索、结构化输出、逐接口验收以及自动化验收与维护。当前 AKShare 基线版本、接口数量和验收结果由自动化报告记录。

为什么选择 AKBridge

AKShare 提供了覆盖广泛的金融数据接口，但把它直接接入 AI 助手仍需要处理 Python 调用、函数选择、参数构造、DataFrame 转换以及版本变化。AKBridge 将这些工作收敛为一个可安装、可检索、可验收的 MCP 服务，让支持 MCP 的 LLM 客户端、Agent 或其他工具可以直接使用 AKShare，而不必为每个应用重复编写适配代码。

AKBridge 适合需要构建金融研究助手、行情分析 Agent、数据检索工具或其他 LLM 金融应用的开发者，尤其适用于以下场景：

• 希望覆盖 AKShare 的完整公共接口，而不是长期手工维护少量工具；
• 希望用户通过自然语言提出需求，由支持 MCP 的 LLM 客户端、Agent 或其他工具完成接口检索和结构化调用；
• 希望只向 LLM 暴露少量稳定的路由工具，降低上千个接口带来的上下文压力；
• 希望获得统一的 JSON 输出、分页、摘要和错误分类，而不是直接处理不同形态的 Python 返回值；
• 希望在 AKShare 更新后自动发现接口变化，并通过逐接口验收判断是否仍可安全使用。

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

验收状态

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

自动化维护

AKBridge 使用 GitHub Actions 和 Dependabot 自动检查 AKShare 更新；同一主版本升级在完整验收通过后自动合并。具体频率、门禁和仓库配置见自动化验收与维护说明。

功能

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

安装

推荐使用 uv 独立安装命令行工具。uv 会为 AKBridge 管理隔离的 Python 3.11+ 环境，不需要把依赖安装到系统 Python。

普通用户请从 PyPI 安装最新发布版：

uv tool install akbridge
uv tool update-shell

重新打开终端后验证安装：

akbridge --help
akbridge --mode router

第二条命令会启动 stdio MCP 服务并等待客户端连接，因此终端看起来没有继续输出是正常现象，可按 Ctrl+C 停止。

如需安装 GitHub 默认分支上的开发版本，可使用：

uv tool install --force "git+https://github.com/kevynf/akbridge.git"

更新或卸载：

# PyPI 安装：升级到最新已发布版本
uv tool upgrade akbridge

uv tool uninstall akbridge

从源码运行

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

git clone https://github.com/kevynf/akbridge.git
cd akbridge
uv sync --group dev
uv run --no-sync akbridge --mode router

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

两种工具模式

all 是默认模式，保留所有已发现的 AKShare 原始函数工具，适合兼容已有客户端、逐接口验收和人工精确调用：

akbridge --mode all

实际连接 LLM 时建议使用 router 模式。它只向客户端公布三个稳定工具：

akbridge --mode router

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

AKShare 文档词法路由

正式发布的 wheel 和 sdist 会在 GitHub Actions 中，根据固定的 AKShare 版本解析对应的 release-vX.Y.Z 标签和 commit SHA，自动构建并包含文档索引。router 模式默认加载包内索引，服务搜索期间不会联网。

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

akbridge-docs build --ref <akshare-commit-sha> --output artifacts\akshare-docs.json
akbridge --mode router --document-index artifacts\akshare-docs.json

文档块会关联 AKShare 顶层公开函数，只补充自然语言术语和排序证据，不决定领域或模块结构。搜索结果会返回命中的文档标题和来源链接；--document-index 仅用于覆盖发布包内置索引。

自动维护报告会记录文档块数量、必填字段完整率、公开接口关联覆盖率以及未关联接口列表；同一摘要显示在 GitHub Actions 的 maintenance Job Summary 中。

客户端配置

选择使用的 MCP 客户端，快速跳转到对应配置：Cherry Studio、Codex或Claude Desktop 与兼容客户端。

Cherry Studio

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

协议安装

将下面的地址复制到浏览器地址栏或 Windows“运行”窗口，打开 Cherry Studio 后检查安装预览并确认：

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

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

如果系统没有打开自定义协议，请使用下方的 JSON 导入方式。

从 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 工具。

Claude Desktop 或兼容客户端配置

支持 JSON MCP 配置的客户端可以使用：

{
  "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 或数据源的正式定义。

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
      },
      {
        "date": "2026-01-05T10:30:00",
        "Open": 10.2,
        "High": 10.5,
        "Low": 10.1,
        "Close": 10.4
      }
    ]
  }
}

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

接口清单

重新生成接口清单：

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

输出文件：

artifacts\acceptance\manifest.json

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

逐接口验收

执行前 20 个待验接口：

.venv\Scripts\python.exe -m akbridge.acceptance run `
  --limit 20 `
  --timeout 30 `
  --workers 4

继续上次进度：

.venv\Scripts\python.exe -m akbridge.acceptance run `
  --resume `
  --limit 100 `
  --timeout 30 `
  --workers 4

复验超时接口：

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

只验收指定接口：

.venv\Scripts\python.exe -m akbridge.acceptance run `
  --name stock_zh_a_hist `
  --name macro_china_cpi `
  --timeout 30

必填验收参数位于：

artifacts\acceptance\fixtures.json

验收状态

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

生成报告

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

主要报告文件：

• artifacts/acceptance/SUMMARY.md：验收汇总。
• artifacts/acceptance/status.svg：README 使用的自动生成状态图。
• artifacts/acceptance/summary.json：机器可读汇总。
• artifacts/acceptance/ledger.csv：全部接口的逐项结果。
• artifacts/acceptance/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

定时任务可加 --check-latest 自动查询 PyPI 是否出现新 AKShare 版本；网络不可用只记录为 unavailable，不会伪装成接口回归。需要在发现新版本时让任务失败时，再加 --fail-on-update。