Skip to main content
Glama
akfamily

io.github.akfamily/aktools

Official
by akfamily
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

AKTools

AKTools exposes AKShare's financial data as an HTTP API and an MCP server, so you can fetch it from any programming language or AI assistant.

PyPI PyPI - Python Version PyPI Downloads Documentation Status Actions Status Ruff Data Science - AKShare MIT Licence GitHub stars GitHub forks GitHub issues

AKTools 把开源财经数据接口库 AKShare 的一千多个接口变成两种开箱即用的服务：

  • HTTP API：一行命令启动服务，C/C++、Java、Go、Rust、JavaScript、R、MATLAB、Stata、Excel 等任何编程语言或软件都能通过网址获取数据。

  • MCP 服务：在 Claude、Cursor 等 AI 助手中直接用自然语言提问，助手会自己查找接口、填写参数并取回数据。

两种方式背后是同一套接口目录、缓存和错误处理，按需选用即可。

AKTools 中文文档 | AKShare 数据字典 | 版本说明

第一次使用？ HTTP API 请从 快速入门教程 开始，约 10 分钟即可完成从安装到下载 Excel 的完整流程；AI 助手请直接看下面的 在 AI 助手中使用。

目录

Related MCP server: AgentLadle MCP AKShare

两种使用方式

通过 HTTP API 获取数据

pip install aktools
python -m aktools

然后在浏览器打开 http://127.0.0.1:8080/api/public/tool_trade_date_hist_sina，看到交易日历数据即表示成功。更多用法见下文的快速开始与调用规则。

在 AI 助手中使用

先安装 uv，再把下面的配置加入 AI 助手的 MCP 配置文件，不需要事先安装 AKTools，也不需要手动启动服务：

{
  "mcpServers": {
    "aktools": {
      "command": "uvx",
      "args": ["--from", "aktools", "aktools-mcp"]
    }
  }
}

重启助手后，就可以直接提问，例如：

  • “帮我查一下贵州茅台 2024 年 10 月 8 日到 11 日的前复权日线行情”

  • “AKShare 里有哪些和可转债相关的接口？”

  • “stock_zh_a_hist 这个接口有哪些参数，复权方式怎么填？”

助手会通过 AKTools 提供的 3 个工具完成查询：search_interfaces 搜索接口、describe_interface 查看参数、get_data 获取数据。下面是在 Claude Code 中实际提问的过程（根据真实会话记录回放）：

在 Claude Code 中提问，AI 助手通过 AKTools 的 MCP 工具查询贵州茅台的日线行情

打开设置中的“开发者 → 编辑配置”，把上面的配置加入 claude_desktop_config.json，保存后重启 Claude Desktop。

claude mcp add aktools -- uvx --from aktools aktools-mcp

点击按钮一键添加：

Add AKTools MCP server to Cursor

也可以手动把上面的配置加入项目的 .cursor/mcp.json，或全局的 ~/.cursor/mcp.json。

已经用 python -m aktools 启动了服务，或者想让多台电脑共用一个服务时，可以让助手直接连接 http://127.0.0.1:8080/mcp，例如：

claude mcp add --transport http aktools http://127.0.0.1:8080/mcp

第一次启动时 uvx 需要下载 AKShare 等依赖（约 150 MB），可能需要几分钟。配置、局域网访问与排障详见 AI 助手（MCP）文档。

特性

  • 两种方式：同一份数据既可以通过 HTTP API 获取，也可以在 Claude、Cursor 等 AI 助手中用自然语言获取

  • 零配置：python -m aktools 一行命令启动服务，无需编写任何代码

  • 接口全覆盖：AKShare 的每个数据接口都可以通过 /api/public/<接口名> 直接访问，AKShare 新增接口后升级即可使用

  • 跨语言：返回标准 JSON，任何能发送 HTTP 请求的语言或软件都可以调用

  • 接口自查：/api/interfaces 列出全部接口并支持按关键词搜索，每个接口的参数、默认值和说明都能直接查询

  • 表格下载：加上 _format=csv 或 _format=xlsx 即可把数据下载为 CSV 或 Excel 文件

  • 结果缓存：同一接口、同样参数在 60 秒内直接返回上次的数据，减少对上游网站的重复请求，降低被封 IP 的风险

  • 自带文档：基于 FastAPI，启动后访问 /docs 即可在线查看和调试接口

  • 便于部署：提供 Dockerfile，支持 Gunicorn + Uvicorn 多进程部署

安装

AKTools 要求 Python 3.11 及以上（64 位），运行环境要求与 AKShare 安装指导 一致。

pip install aktools

AKShare 的数据接口会随上游网站的变化频繁更新，遇到问题时请先把两者都升级到最新版：

pip install akshare aktools --upgrade -i https://pypi.org/simple

快速开始

  1. 启动服务：

    python -m aktools

  2. 浏览器打开以下地址：

    地址

    说明

    http://127.0.0.1:8080/

    主页，展示简要的使用说明

    http://127.0.0.1:8080/docs

    接口导览，可在线调试

    http://127.0.0.1:8080/version

    当前与最新的 AKShare、AKTools 版本

    http://127.0.0.1:8080/api/interfaces?q=历史行情

    按关键词搜索接口

    http://127.0.0.1:8080/api/interfaces/stock_zh_a_hist

    查看接口的参数、默认值和说明

    http://127.0.0.1:8080/api/public/tool_trade_date_hist_sina

    连通性测试（新浪交易日历，无需参数且较为稳定）

    http://127.0.0.1:8080/api/public/stock_zh_a_hist?symbol=600000

    带参数获取数据

启动参数：

参数

简写

默认值

说明

--host

-H

127.0.0.1

监听地址，需要局域网或其他机器访问时设置为 0.0.0.0

--port

-P

8080

监听端口

--auto

-A

关闭

启动后自动打开浏览器

--cache-ttl

—

60

结果缓存的有效期（秒），同一接口、同样参数在有效期内直接返回上次的数据，0 为关闭

--akshare-cache-clear

—

3600

清空 AKShare 内部缓存的间隔（秒），避免板块名称等数据一直不更新，0 为关闭

--proxy

—

不设置

访问上游数据源使用的代理，如 http://127.0.0.1:7890；不设置时沿用 HTTP_PROXY 等环境变量

--timeout

—

60

访问上游数据源的读取超时（秒），连接超时固定为 10 秒

--version

-v

—

查看 AKTools 版本

例如：python -m aktools --port 8888 --auto 会在 8888 端口启动并自动打开浏览器。需要让局域网内的其他机器访问时，加上 --host 0.0.0.0，其他机器通过 http://<本机 IP>:8888 访问；0.0.0.0 只表示监听所有网卡，不能当作访问地址在浏览器中打开。

调用规则

AKTools 本身不加工数据，只负责把 HTTP 请求翻译成对 AKShare 接口的调用：

GET /api/public/{接口名}?{参数1}={值1}&{参数2}={值2}
        ↓
akshare.{接口名}(参数1="值1", 参数2="值2")

  • 接口名与 AKShare 的函数名完全一致。可以通过 /api/interfaces?q=关键词 搜索接口，通过 /api/interfaces/{接口名} 查看参数说明，详细的数据说明请查阅 AKShare 数据字典。

  • 参数以查询字符串传递，值不需要加引号，例如 ?symbol=600000&period=weekly；不传的参数使用 AKShare 接口的默认值。

  • 返回值默认是由 DataFrame 按行转换得到的 JSON 数组，日期时间字段为 ISO 8601 格式，例如 "2024-01-25T00:00:00.000"。

  • 下载表格：加上保留参数 _format=csv 或 _format=xlsx，数据会以 {接口名}.csv 或 {接口名}.xlsx 文件下载，例如 /api/public/stock_zh_a_hist?symbol=000001&_format=xlsx。CSV 为带 BOM 的 UTF-8 编码，可以直接用 Excel 打开。

请求失败时返回 {"error": "错误信息"}，状态码含义如下：

状态码

含义

处理建议

200

成功

—

400

参数不合法，_format 取值不支持，或数据行数超过 Excel 上限

对照 /api/interfaces/{接口名} 检查参数；_format 改用 json、csv 或 xlsx，数据过大时改用 csv

404

接口名不存在，或接口调用出错

升级 AKShare，并对照 /api/interfaces/{接口名} 检查接口名和参数

429

上游数据源限制了访问频率

稍后重试，或调大 --cache-ttl 减少重复请求

502

无法访问上游数据源、上游返回错误，或上游页面改版导致解析失败

检查网络和代理设置，见 常见问题；解析失败时升级 AKShare

多语言调用示例

以下示例均假设服务运行在 http://127.0.0.1:8080，请按实际地址和端口修改。

curl "http://127.0.0.1:8080/api/public/stock_zh_a_hist?symbol=000001&period=daily&start_date=20240101&end_date=20240131&adjust=qfq"
import pandas as pd
import requests

url = "http://127.0.0.1:8080/api/public/stock_zh_a_hist"
params = {
    "symbol": "000001",
    "period": "daily",
    "start_date": "20240101",
    "end_date": "20240131",
    "adjust": "qfq",
}
r = requests.get(url, params=params, timeout=30)
r.raise_for_status()
df = pd.DataFrame(r.json())
print(df)
library(RCurl)    # 需要先安装该包
library(jsonlite) # 需要先安装该包
options(warn = -1) # 去掉无参数请求时的 warning 信息

temp_df <- getForm(
  uri = "http://127.0.0.1:8080/api/public/stock_zh_a_hist",
  symbol = "000001",
  period = "daily",
  start_date = "20211109",
  end_date = "20211209",
  adjust = "hfq",
  .encoding = "utf-8"
)
inner_df <- fromJSON(temp_df)
inner_df
api = 'http://127.0.0.1:8080/api/public/';
url = [api 'stock_zh_a_hist'];
options = weboptions('ContentType', 'json', 'CharacterEncoding', 'utf-8');
data = webread(url, 'symbol', '000001', 'period', 'daily', ...
    'start_date', '20211109', 'end_date', '20211209', 'adjust', 'hfq', options);
data % MATLAB 无法显示中文字段名，可自行改为英文字段

依赖：reqwest（启用 blocking 与 json 特性）和 serde_json。

use reqwest::blocking;
use serde_json::Value;

const URL: &str = "http://127.0.0.1:8080/api/public";

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let params = [
        ("symbol", "000001"),
        ("period", "daily"),
        ("start_date", "20240125"),
        ("end_date", "20240126"),
        ("adjust", ""),
    ];
    let resp = blocking::Client::new()
        .get(format!("{URL}/stock_zh_a_hist"))
        .query(&params)
        .send()?;

    if resp.status().is_success() {
        let data: Value = resp.json()?;
        println!("{data:#?}");
    } else {
        eprintln!("请求失败，状态码为：{}", resp.status());
    }
    Ok(())
}

更多示例及运行结果，请见 多语言调用。

部署

Docker

使用仓库中的 Dockerfile 构建镜像，镜像默认以 Gunicorn 管理多个 Uvicorn worker 运行：

docker build -t aktools .
docker run -d -p 8080:8080 aktools

国内网络环境下可以指定 PyPI 镜像源加速构建：

docker build --build-arg PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ -t aktools .

镜像升级等更多说明，请见 部署文档。

生产环境

python -m aktools 适合本地使用。生产环境建议直接用 Gunicorn 启动 aktools.main:app：

pip install gunicorn uvicorn-worker
AKTOOLS_HOST=0.0.0.0 gunicorn aktools.main:app --bind 0.0.0.0:8080 --workers 4 --worker-class uvicorn_worker.UvicornWorker

AKTools 不带鉴权功能。如果服务需要暴露到公网，请在前面加一层带鉴权的反向代理（如 Nginx）。

常见问题

返回 502，提示“访问上游数据源失败”

运行 AKTools 的机器无法访问东方财富、新浪财经等上游网站，通常是代理配置导致的。报错中如果出现 ProxyError 或 Unable to connect to proxy，请检查或清除代理相关的环境变量后重启服务：

# Linux / macOS
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
# Windows PowerShell
Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY

部分接口要求在境内网络环境下访问，详见 AKShare 文档中对应接口的说明。

返回 404，提示“未找到该接口”或“调用接口出错”

先升级 AKShare 到最新版，然后用 /api/interfaces?q=关键词 搜索正确的接口名，用 /api/interfaces/{接口名} 检查参数名和可选值。也可以在 Python 中直接调用同名的 AKShare 接口，确认问题是否出在 AKShare。

数据没有及时更新

同一接口、同样参数的请求在 60 秒内会返回缓存的数据，响应头 X-AKTools-Cache: hit 表示数据来自缓存，启动时加上 --cache-ttl 0 可关闭缓存。板块名称等数据由 AKShare 内部缓存，默认每小时清空一次，可用 --akshare-cache-clear 调整。

数据有误或接口报错，应该去哪里反馈？

AKTools 只负责转发请求，数据内容由 AKShare 提供。如果在 Python 中直接调用 AKShare 也有同样的问题，请到 AKShare Issues 反馈；只有 AKTools 自身的问题（启动、路由、序列化等）才需要到 AKTools Issues 反馈。

参与贡献

欢迎提交 Issue 和 Pull Request！开发环境的搭建、代码检查与提交规范请见 贡献指南。参与本项目即表示您同意遵守 贡献者行为准则。

免责声明

AKTools 与 AKShare 提供的数据仅供学术研究使用，不构成任何投资建议。数据均来自公开的网络数据源，请在使用前自行核实，并遵守相关数据源的使用条款。因使用本项目造成的任何直接或间接损失，项目作者及贡献者不承担任何责任。

许可证

本项目基于 MIT 许可证 开源。

Available Tools

3 tools
describe_interfaceB

查看接口的标题、数据源地址，以及各参数的默认值、类型和说明

NameRequiredDescriptionDefault
nameYes接口名，如 stock_zh_a_hist

Output Schema

NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must carry behavioral weight, and it does disclose the returned fields (title, source address, param metadata) and that it is a read/inspect operation. However, it says nothing about error behavior when an interface name is invalid, or any auth/rate constraints, leaving meaningful gaps for a no-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence with zero waste that front-loads the action and enumerates the returned content. Nothing is redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple one-parameter read tool and an output schema exists, so return-value explanation is unnecessary. The description covers purpose and returned content adequately; only minor gaps around invalid-name behavior and alternative routing keep it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'name' parameter is well documented in the schema, including an example (stock_zh_a_hist). The description adds no syntax or formatting detail beyond what the schema already provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (查看/view) and resource (接口/interface) and enumerates exactly what is returned: title, data-source address, and each parameter's default value, type, and description. This clearly distinguishes it as an inspection tool versus search_interfaces (discovery) and get_data (data retrieval), though it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use / when-not-to-use guidance and no mention of alternatives such as search_interfaces when the interface name is unknown. The inspect-before-fetch pattern is only inferable from the sibling names, not from the description itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dataA

调用 AKShare 接口获取数据。数据量大时只返回前 max_rows 行，并给出总行数；随 HTTP 服务运行时还给出完整数据的 CSV 下载地址

NameRequiredDescriptionDefault
nameYes接口名，如 stock_zh_a_hist
paramsNo接口参数，如 {"symbol": "000001", "start_date": "20240101"}
max_rowsNo最多返回的行数，默认 100

Output Schema

NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does disclose important traits: large results are truncated to max_rows, the total row count is returned, and an HTTP-mode CSV download URL is provided. It still omits error behavior, rate limits, and explicit read-only/network caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single compact sentence that front-loads the core purpose and then adds the most relevant output behavior. There is no redundant or empty phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The input schema is fully documented and an output schema exists, so the description does not need to explain return structure. It covers the important truncation and CSV behavior, though it could do more to clarify the workflow relative to the sibling discovery tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents name, params, and max_rows. The description adds meaningful behavior beyond the schema by explaining that max_rows controls truncation and that the total row count and CSV URL are returned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear action and mechanism: retrieve data by calling an AKShare interface. It is specific enough to understand what the tool does, but it does not explicitly distinguish itself from the sibling search_interfaces and describe_interface tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the tool executes a named AKShare interface, while sibling tools likely help discover or describe interfaces. The description never states when to use this tool instead of search_interfaces or describe_interface, nor whether an interface must be described first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_interfacesA

按关键词搜索 AKShare 数据接口，返回接口名与中文标题。结果较多时只返回前 50 个，请换用更具体的关键词

NameRequiredDescriptionDefault
keywordYes关键词，匹配接口名或中文标题，如“历史行情”“交易日历”

Output Schema

NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and does disclose the key behavioral trait: results are truncated to the first 50, with the prescribed remedy. It omits other traits such as ranking/ordering of matches or empty-result behavior, but the most consequential limit is front and center.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence: purpose first, return value second, truncation caveat last. No filler, and the limit warning is placed where a caller will hit it rather than buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter search with an output schema, the description covers what it does, what it returns, and its result cap, which is enough to call it correctly. Only the workflow position relative to describe_interface and get_data is unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single keyword parameter is fully documented in the schema (matches interface name or Chinese title, with examples). The description restates that it searches by keyword but adds no syntax, format, or matching nuance beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (搜索) and resource (AKShare 数据接口), plus what is returned (接口名与中文标题). It does not differentiate against the siblings describe_interface/get_data, so an agent must infer that this is the discovery step rather than the metadata or data-fetch step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable usage context: search by keyword, and when the result set is large, narrow the keyword instead of paging. It never names describe_interface or get_data as follow-up steps, so the routing to siblings is left implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observeddescribe_interface
    • First observedget_data
    • First observedsearch_interfaces
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

The three tools map cleanly to a discovery → inspection → retrieval workflow: search_interfaces finds interfaces, describe_interface explains one interface, and get_data fetches its data. There is no meaningful overlap between their purposes.

Naming Consistency5/5

All names use a consistent snake_case verb_noun pattern (search_interfaces, describe_interface, get_data). The singular/plural difference follows naturally from whether the operation targets one interface or many.

Tool Count5/5

Three tools are well-scoped for a gateway to a large external API catalog. Each tool has a distinct and necessary role, with no redundant operations.

Completeness4/5

The search, describe, and fetch surface covers the core workflow for using AKShare interfaces. A minor gap is the lack of pagination or a full interface listing, though the search tool tells agents to refine keywords instead.

Maintenance

ActivityMaintained
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

  • AKShare MCP Server

    jadenmong
    A
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to access comprehensive Chinese financial market data including stocks, funds, futures, and economic indicators via AKShare.
    5
    5
    MIT

  • AgentLadle MCP AKShare

    agentladle
    A
    license
    A
    quality
    C
    maintenance
    Provides 46 financial data tools for AI assistants covering A-share, HK, US markets, macroeconomics, funds, and derivatives, powered by AKShare.
    54
    38 PyPI
    MIT

  • AKBridge MCP Server

    kevynf
    A
    license
    A
    quality
    A
    maintenance
    Connects AKShare's extensive financial data interfaces to the Model Context Protocol (MCP), enabling LLM clients and agents to search, describe, and call these interfaces via natural language. Provides structured JSON output, pagination, routing, and automated validation to simplify data retrieval while maintaining reliability.
    3
    233 PyPI
    MIT

  • mcp-stock-quote

    JingHao-Leon
    A
    license
    A
    quality
    B
    maintenance
    Enables AI assistants to fetch realtime stock quotes, fundamentals, and search for stocks across A-share, Hong Kong, and US markets without requiring API keys.
    5
    13 npm
    MIT