📊 a-share-mcp 📈

本项目是一个基于专注于 A 股市场的 MCP 服务器，它提供股票基本信息、历史 K 线数据、财务指标、宏观经济数据等多种查询功能，理论上来说，可以回答有关 A 股市场的任何问题，无论是针对大盘还是特定股票。

项目结构

Related MCP server: MCP Yahoo Finance

功能特点

先决条件

1. Python 环境: Python 3.10+

2. 依赖管理: 使用 uv 包管理器安装依赖

3. 数据来源: 基于 Baostock 数据源，无需付费账号。在此感谢 Baostock。

4. 提醒：本项目于 Windows 环境下开发。

数据更新时间

以下是 Baostock 官方数据更新时间，请注意查询最新数据时的时间点 Baostock 官网

每日数据更新时间：

• 当前交易日 17:30，完成日 K 线数据入库

• 当前交易日 18:00，完成复权因子数据入库

• 第二自然日 11:00，完成分钟 K 线数据入库

• 第二自然日 1:30，完成前交易日"其它财务报告数据"入库

• 周六 17:30，完成周线数据入库

每周数据更新时间：

• 每周一下午，完成上证 50 成份股、沪深 300 成份股、中证 500 成份股信息数据入库

所以说，在交易日的当天，如果是在 17:30 之前询问当天的数据，是无法获取到的。

安装环境

在项目根目录下执行：

要启动 A 股 MCP 服务器，请按照以下步骤操作：

使用：在 MCP 客户端中配置服务器

在支持 MCP 的客户端（如 VS Code 插件、CherryStudio 等）中，你需要配置如何启动此服务器。 推荐使用 。

方法一：使用 JSON 配置的 IDE (例如 Cursor、VSCode、Trae 等)

对于需要编辑 JSON 文件来配置 MCP 服务器的客户端，你需要找到对应的能配置 MCP 的地方（各个 IDE 和桌面 MCP Client 可能都不一样），并在 mcpServers 对象中添加一个新的条目。

JSON 配置示例 (请将路径替换为你的实际绝对路径):

注意事项:

• command: 确保填写的 uv 命令或 uv.exe 的绝对路径是客户端可以访问和执行的。

• args: 确保参数列表完整且顺序正确。

• 路径转义: 路径需要写成双反斜杠 \\。

  这是 Windows 系统特有的情况。如果是在 macOS 或 Linux 系统中，路径使用正斜杠/作为目录分隔符，就不需要这种转义处理。

• workingDirectory: 虽然 uv --directory 应该能解决工作目录问题，但如果客户端仍然报错 ModuleNotFoundError，可以尝试在客户端配置中明确设置此项为项目根目录的绝对路径。

方法二：使用 CherryStudio

在 CherryStudio 的 MCP 服务器配置界面中，按如下方式填写：

• 名称: a-share-mcp (或自定义)

• 描述: 本地 A 股 MCP 服务器 (或自定义)

• 类型: 选择 标准输入/输出 (stdio)

• 命令: uv (或者填系统中绝对路径下 uv.exe)

• 包管理源: 默认

• 参数:

  1. 第一个参数填: --directory

  2. 第二个参数填: C:\\Users\\YourName\\Projects\\a_share_mcp

  3. 第三个参数填: run

  4. 第四个参数填: python

  5. 第五个参数填: mcp_server.py

  • 确保所有参数按下回车转行隔开的，否则报错（是不是手把手教学了？）

• 环境变量: (通常留空)

Tricks（必看）: 有时候在 Cherrystudio 填写好参数后，点击右上方的开关按钮，会发现没任何反应，此时只要随便点击左侧目录任一按钮，跳出 mcp 设置界面，然后再回到 mcp 设置界面，就会发现 mcp 已经闪绿灯配置成功了。

CherryStudio 使用示例: 理论上来说，你可以问有关 A 股的任何问题 :)

重要提示:

• 确保命令字段中的 uv 或其绝对路径有效且可执行。

• 确保参数字段按顺序正确填写了五个参数。

工具列表

该 MCP 服务器目前提供 40 个工具，覆盖股票、财报、宏观、日期分析等全方位数据。以下是完整列表：

贡献指南

欢迎提交 Issue 或 Pull Request 来帮助改进项目。贡献前请先查看现有 Issue 和文档。

☕️ 请作者喝杯咖啡

如果这个项目对你有帮助，欢迎请我喝杯咖啡 ❤️

许可证

本项目采用 MIT 许可证 - 详情请查看 LICENSE 文件

本次更新概览（2025-12）

本次更新（version 2025.12.06）主要集中在 架构重构 与 工具链标准化，旨在为 AI Agent 提供更稳定、更“懂行”的数据服务。

🚀 架构升级 (Refactor)

• Clean Architecture: 引入了 Use Case 层，将业务逻辑与接口适配层（Tools）彻底解耦，提升了代码的可维护性与测试性。

• 统一错误处理: 实现了全局的 run_tool_with_handling 机制，统一管理异常捕获、日志记录和错误返回格式，大幅提升系统稳定性。

• 强类型校验: 增强了对输入参数（如季度、日期格式、代码规范）的即时校验，减少无效请求。

✨ 新增功能

• 智能日期工具:

  • get_market_analysis_timeframe: 让 AI 能理解“最近”、“本季度”等自然语言时间概念。

  • get_last_n_trading_days: 自动计算最近 N 个交易日，自动跳过节假日。

• 通用能力增强:

  • 所有列表类工具均支持 limit（条数限制）和 format（markdown/json/csv）参数，方便 AI 根据场景按需索取数据格式。

🛠️ 兼容性说明

• 新增参数均为可选参数，保持了对旧版本的向后兼容性。

• 默认输出格式维持 Markdown，确保在大多数 MCP 客户端中即插即用。