mcp_zhitou_server
mcp_zhitou_server
✨ Zhitou HS Data MCP Server (Python Edition) ✨
empowering AI Agents like Cursor & Cline with real-time China A-Share stock market data! 🚀
Hey Coder 小伙伴们！👋 我是 PGFA！欢迎来到我的 Zhitou HS Data MCP Server 项目！
这个项目是一个用 Python 编写的 模型上下文协议 (MCP) 服务端实现。它的核心使命是充当你的 AI 智能体（比如超火的 Cursor 编辑器或 Cline 命令行助手）和 智兔数服沪深数据 API (https://www.zhituapi.com/hsstockapi.html) 之间的桥梁 🌉。
简单来说，有了它，你就可以直接在 AI Agent 的聊天框里，用自然语言让 AI 帮你查询实时的 A 股股票列表、公司信息、资金流向等等，再也不用手动去查啦！是不是超级酷炫，效率 up up！📈
🌟 主要特性
- MCP 标准实现: 通过标准输入/输出 (stdio) 与兼容 MCP 的客户端进行 JSON-RPC 通信。
- 直连 Zhitou API: 无缝对接智兔数服提供的丰富沪深市场数据接口。
- Python 编写: 代码简洁易懂，方便二次开发和扩展。 (Python大法好！🐍)
- 即插即用: 提供清晰的配置指南，轻松在 Cursor 或 Cline 中启用。
- 工具化封装: 将常用的 Zhitou API 封装成 MCP 工具，方便 AI 调用。
- 基础日志与错误处理: 包含必要的日志记录和异常处理，方便调试。
🛠️ 快速开始
跟上 PGFA 的节奏，三步搞定！
1. 环境准备 (Prerequisites)
- Python: 确认你的环境安装了 Python (推荐 3.8 或更高版本)。
- Requests 库: 我们需要它来调用 API。打开你的终端/命令行，运行：
pip install requests- 智兔 API Token: 你必须拥有一个智兔数服 (https://www.zhituapi.com/) 的账号，并获取你的 API Token。
- MCP 客户端: 安装 Cursor (https://cursor.sh/) 或 Cline ()。
2. 获取代码 & 配置 Token
- 下载本仓库唯一文件mcp_zhitou_server.py
- 🔥【宇宙级重要】🔥 配置你的 API Token:
打开主脚本文件 mcp_zhitou_server.py (或者你命名的其他主文件)，找到下面这行：
# 🔥🔥🔥【请务必替换为你自己的有效 Token! 测试 Token 有限制!】🔥🔥🔥
ZHITU_TOKEN = "ZHITU_TOKEN_LIMIT_TEST"将 "ZHITU_TOKEN_LIMIT_TEST" 替换成你自己在智兔数服获取到的真实 API Token！ 否则服务无法正常工作哦！
3. 配置 MCP 客户端
根据你使用的客户端进行配置：
- 如果你用 Cline:
1. 打开 Cline (独立版或 VS Code 插件均可)。 2. 进入设置，找到 MCP Servers 管理界面。 3. 添加一个新的 MCP Server。 4. Name: 随意填，比如 Zhitou_HS_API。 5. Command: 填入完整的 Python 解释器路径和你保存的脚本绝对路径。 * *Mac/Linux 示例:* /usr/local/bin/python3 /path/to/your/project/mcp_zhitou_server.py * *Windows 示例:* C:\Python311\python.exe C:\Users\PGFA\project\mcp_zhitou_server.py (路径请根据你的实际情况修改！) 6. 保存配置。启动 Cline 后，应该能看到这个 Server 处于连接状态。
- 如果你用 Cursor:
1. 在你的项目根目录下，创建一个名为 .cursor 的文件夹（如果不存在）。 2. 在 .cursor 文件夹内，创建一个名为 mcp.json 的文件。 3. 将以下 JSON 内容粘贴进去，并修改 args 中的脚本路径为你的实际绝对路径：
{
"mcpServers": {
"zhitou_hs": { // 服务器的唯一标识符，可以自定义
"command": "python", // 或 python3
"args": ["/path/to/your/project/mcp_zhitou_server.py"], // ⚠️⚠️⚠️ 修改为你的脚本实际路径！
// "workingDirectory": "/path/to/your/project/", // 可选，但建议设置
"tools": [
// 建议把你实现的工具在这里声明一下，方便 Agent 发现
{"name": "get_stock_list", "description": "获取基础 A 股股票列表 (代码, 名称, 交易所)。"},
{"name": "get_new_stock_calendar", "description": "获取新股日历 (申购信息, 上市日期等)。"},
{"name": "get_company_profile", "description": "获取指定股票代码的上市公司简介。", "parameters": {"stock_code": {"type":"string", "description": "股票代码, e.g., '000001'"}}},
{"name": "get_capital_daily_trend", "description": "获取指定股票代码的每日资金流入趋势 (近十年)。", "parameters": {"stock_code": {"type":"string"}}},
{"name": "get_all_announcements", "description": "获取指定股票代码的历史所有公告列表。", "parameters": {"stock_code": {"type":"string"}}}
// ... 如果添加了更多工具，也在这里声明 ...
]
}
}
}4. 保存 mcp.json 文件。重启 Cursor 或让它重新加载项目配置。
4. 开始玩耍！🎉
现在，打开你的 Cursor 或 Cline 聊天窗口，试试用自然语言和 AI 对话，让它调用我们定义的工具吧！
- "用
get_stock_list工具帮我看看最新的股票列表。" - "查询一下 000001 的公司简介，使用
get_company_profile工具。" - "今天的新股日历是啥？" (AI 应该会选择
get_new_stock_calendar) - "帮我看看股票 600519 最近的所有公告。" (AI 应该会选择
get_all_announcements)
观察 AI 的回复和你的终端日志，享受 AI 帮你干活的乐趣吧！😉
🔧 可用工具列表 (Tools Available)
当前已实现的 MCP 工具 (对应 Python 函数)：
get_stock_list: 获取基础 A 股股票列表 (代码, 名称, 交易所)。get_new_stock_calendar: 获取新股日历 (申购信息, 上市日期等)。get_company_profile: 获取指定股票代码的上市公司简介。(需要stock_code参数)get_capital_daily_trend: 获取指定股票代码的每日资金流入趋势 (近十年)。(需要stock_code参数)get_all_announcements: 获取指定股票代码的历史所有公告列表。(需要stock_code参数)- *(欢迎添加更多工具！)*
🚀 如何扩展？(Adding More Tools)
想让你的 AI 助手更强大？完全 OK！
- 查阅智兔 API 文档: 找到你想添加功能的 API 端点。
- 编写 Python 函数: 在
mcp_zhitou_server.py中，仿照现有的工具函数，编写一个新的函数来调用这个 API，记得处理好参数和返回值。给函数写上清晰的docstring哦！ - 注册工具: 在
TOOLS字典里，添加一行，把新的工具名和你刚写的函数关联起来。 - (可选) 更新客户端配置: 如果你的客户端配置 (如 Cursor 的
mcp.json) 需要显式声明工具列表，记得把新工具加进去。 - 重启你的 MCP 服务（通常客户端会自动重启或重新连接）。
搞定！你的 AI 又解锁了新技能！😎
📜 许可证 (License)
本项目采用 MIT 许可证。
🙏 致谢 (Acknowledgements)
- 感谢 智兔数服 提供稳定易用的沪深数据 API。
- 感谢 Anthropic 提出 MCP 协议，开启了 AI Agent 的新时代。
- 感谢屏幕前的你！点个 Star ⭐ 支持一下 PGFA 吧！
希望这份 README 对你有帮助！快去试试看，让你的 AI 动起来吧！有问题欢迎在 Issues 区提出。Have Fun Coding! 💖
