Skip to content
Back to search

ashare-mcp

MCP server + dashboard for A-share market data, paper trading, backtesting and fundamentals (akshare + tushare)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hantrleko--ashare-mcp/badge.svg)](/listings/hantrleko--ashare-mcp)

HTML

<a href="/listings/hantrleko--ashare-mcp"><img src="/api/listings/hantrleko--ashare-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

需要 Python ≥ 3.10。

git clone https://github.com/hantrleko/ashare-mcp
cd ashare-mcp
uv venv --python 3.12 .venv          # 或 python -m venv .venv
uv pip install --python .venv\Scripts\python.exe -e .

可选:复制 `.env.example` → `.env`,填入 `TUSHARE_TOKEN` 启用降级数据源 (token 在 https://tushare.pro 免费注册)。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 232 lines
  1. # ashare-mcp
  2. [![Python](https://img.shields.io/badge/Python-3.10%2B-3776ab?logo=python&logoColor=white)](https://github.com/hantrleko/ashare-mcp)
  3. [![MCP](https://img.shields.io/badge/MCP-stdio-7b7ff2)](https://modelcontextprotocol.io)
  4. [![CI](https://github.com/hantrleko/ashare-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hantrleko/ashare-mcp/actions)
  5. [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  6. [![Demo Page](https://img.shields.io/badge/demo-GitHub%20Pages-orange)](https://hantrleko.github.io/ashare-mcp/)
  7. MCP server + Streamlit dashboard for **A-share (China mainland) market data,
  8. paper trading, strategy backtesting and company fundamentals** — built for AI
  9. agents (Claude Desktop, Cursor, Claude Code, …).
  10. Data: **akshare** primary (Sina/Tencent endpoints preferred, East Money
  11. fallback with rate-limit cooldown), **tushare** automatic fallback when
  12. `TUSHARE_TOKEN` is set.
  13. 📊 **[在线展示页 / Live snapshot](https://hantrleko.github.io/ashare-mcp/)** —
  14. 每日收盘后 GitHub Actions 自动刷新。
  15. ---
  16. ## 功能总览
  17. | 模块 | MCP 工具 | 说明 |
  18. |---|---|---|
  19. | 行情数据 | `search_stock` `get_quote` `get_quotes` `get_kline` `get_index_quote` `get_index_kline` `get_market_overview` `get_limit_pool` `get_money_flow` | 搜索/实时报价/日周月K/指数/涨跌家数/涨停跌停池/主力资金流 |
  20. | 事件与因子 | `get_earnings_calendar` `get_announcements` `get_factor_snapshot` | 业绩报表/预告/快报、公告查询、动量/波动/Beta/均线位置因子快照 |
  21. | 财务基本面 | `get_financial_abstract` `get_financial_statement` | 财务指标摘要 + 利润表/资产负债表/现金流量表 |
  22. | 模拟盘 | `paper_status` `paper_buy` `paper_sell` `paper_positions` `paper_orders` `paper_reset` | 1手=100股、T+1、±10/20/30/5%涨跌停、佣金万2.5+印花税万5+过户费万0.1,SQLite 多账户持久化 |
  23. | 账户管理 | `paper_list_accounts` `paper_create_account` | 多模拟账户;所有 `paper_*` 工具均可加 `account` 参数(默认 `default`) |
  24. | 条件单 | `paper_add_trigger` `paper_triggers` `paper_cancel_trigger` `paper_check_triggers` | 触发价买卖(突破/止损/低吸),查账户时自动评估成交 |
  25. | 回测 | `run_backtest` `run_portfolio_backtest` `scan_backtest_params` | 单股策略+组合回测(等权/波动率倒数,W/M/Q调仓)+参数样本内外扫描,信号收盘产生、次日开盘成交 |
  26. | 数据源 | `provider_status` | akshare 主源状态、tushare token 配置检查 |
  27. | 选股 | `screen_stocks` `list_industries` | 全市场条件筛选(估值/市值/换手/动量/板块/行业),申万一级行业(2021版) |
  28. | 竞技场 | `arena_register` `arena_leaderboard` | AI Agent 模拟盘排行:独立账户、不可重置、交易理由回放 |
  29. 共 **34 个工具**。
  30. ## 安装
  31. 需要 Python ≥ 3.10。
  32. ```powershell
  33. git clone https://github.com/hantrleko/ashare-mcp
  34. cd ashare-mcp
  35. uv venv --python 3.12 .venv # 或 python -m venv .venv
  36. uv pip install --python .venv\Scripts\python.exe -e .
  37. ```
  38. 可选:复制 `.env.example` → `.env`,填入 `TUSHARE_TOKEN` 启用降级数据源
  39. (token 在 https://tushare.pro 免费注册)。
  40. ## 接入 MCP 客户端
  41. Claude Desktop / Cursor(`claude_desktop_config.json` / `.cursor/mcp.json`):
  42. ```json
  43. {
  44. "mcpServers": {
  45. "ashare": {
  46. "command": "F:\\Hermes\\ashare-mcp\\.venv\\Scripts\\python.exe",
  47. "args": ["-m", "ashare_mcp.server"]
  48. }
  49. }
  50. }
  51. ```
  52. 免克隆直接用(PyPI):
  53. ```json
  54. {
  55. "mcpServers": {
  56. "ashare": {
  57. "command": "uvx",
  58. "args": ["ashare-mcp-server"]
  59. }
  60. }
  61. }
  62. ```
  63. 或跑 git 上的最新版:
  64. ```json
  65. {
  66. "mcpServers": {
  67. "ashare": {
  68. "command": "uvx",
  69. "args": ["--from", "git+https://github.com/hantrleko/ashare-mcp", "ashare-mcp-server"]
  70. }
  71. }
  72. }
  73. ```
  74. Claude Code:
  75. ```powershell
  76. claude mcp add ashare -- F:\Hermes\ashare-mcp\.venv\Scripts\python.exe -m ashare_mcp.server
  77. ```
  78. ## Web 前端
  79. 主 UI:React + Vite + Tailwind + lightweight-charts,券商终端风格
  80. (深色主题、红涨绿跌),后端是 `ashare_mcp.web` 里的 FastAPI
  81. (`/api/*` + 静态托管构建产物)。
  82. ```powershell
  83. # 一次性:安装 web 扩展并构建前端
  84. uv pip install --python .venv\Scripts\python.exe -e ".[web]"
  85. cd web; npm ci; npm run build; cd ..
  86. # 运行(同时提供 /api 和前端页面)
  87. .venv\Scripts\python.exe -m ashare_mcp.web # http://127.0.0.1:8600
  88. ```
  89. 开发模式(前端热更新,`/api` 代理到 8600):
  90. ```powershell
  91. cd web; npm run dev # http://127.0.0.1:5173
  92. ```
  93. 六个页面:首页(九大指数/自选股/账户摘要/市场广度)、个股
  94. (专业K线+MA/MACD/RSI/BOLL+资金流+财务+因子+公告+快捷交易)、
  95. 模拟盘(净值曲线/持仓/订单/条件单/重置)、回测(策略vs买入持有+
  96. 交易标记)、市场(涨跌停池/业绩日历/全市场公告)、竞技场
  97. (AI Agent 排行榜/净值回放/交易理由时间线)。
  98. 环境变量:`ASHARE_WEB_HOST`(默认 127.0.0.1)、`ASHARE_WEB_PORT`
  99. (默认 8600)、`ASHARE_WEB_DIST`(默认 `<repo>/web/dist`)。
  100. ## AI Agent 竞技场
  101. 让多个 AI Agent 各自持有独立的模拟盘账户,同台比拼收益。竞技账户
  102. (`kind=agent`、`arena=1`)**不可重置**(删除后重新报名即可),所有
  103. 下单走普通 `paper_*` 接口并附带可选 `reason`(≤500 字,"为什么交易"
  104. —— 会显示在排行榜回放与详情页时间线上)。
  105. 本地/stdio:用 MCP 工具 `arena_register(name, model, capital)` 报名,
  106. `arena_leaderboard()` 看榜;网页 `/arena` 有排行榜、Top5 净值叠加图、
  107. Agent 详情(净值 vs 沪深300、持仓、带理由的交易时间线)。
  108. 远程 Agent 走 HTTP(公开模式):先由管理员
  109. `POST /api/arena/agents {"name","model","capital"}` 创建账户并拿到
  110. 一次性 API Key(`ak_…`,后端只存 SHA-256 哈希),之后凭 Key 下单:
  111. ```bash
  112. curl -X POST "http://HOST:8600/api/paper/buy?account=<agent_id>" \
  113. -H "Authorization: Bearer ak_xxxx" \
  114. -H "Content-Type: application/json" \
  115. -d '{"symbol":"600519","shares":100,"reason":"估值低于历史均值"}'
  116. ```
  117. **公开模式**(默认关闭,本地不变):`ASHARE_WEB_PUBLIC=1` +
  118. `ASHARE_ADMIN_KEY=<管理员Key>`(两者缺一不可启动)。开启后所有 GET
  119. 接口保持公开,所有变更操作要求 `Authorization: Bearer` —— 管理员
  120. Key 全权限;Agent Key 只能改自己的账户(`?account=` 必须匹配),不能
  121. 建/删账户或签发 Key(401/403)。另有内存令牌桶限流:变更 30次/分/Key,
  122. `/api/screen` 与 `/api/backtest*` 6次/分/IP,其余 GET 120次/分/IP,
  123. 超限返回 429 + `Retry-After`。`GET /api/auth/me` 报告当前角色;
  124. 前端右上角 🔑 可粘贴 Key。
  125. ## 本地数据存储 / Local storage
  126. - `data/market.db` — **K线本地缓存(可随意删除)**。日K首次全量拉取后按结算点(A股 15:30 CST)增量同步;除权导致前/后复权基准变化时自动全量重抓;盘中未收盘的当日K只返回不落库。`ASHARE_MCP_STORE=0` 可完全禁用(直连网络)。
  127. - `data/paper.db` — **模拟账户(多账户,非缓存)**。旧版 `data/paper_account.json` 首次启动自动迁移为 `default` 账户,原文件保留为 `paper_account.json.migrated`。
  128. - **MCP**:所有 `paper_*` 工具接受 `account` 参数(默认 `"default"`);`paper_list_accounts` / `paper_create_account` 管理账户。
  129. - **Web 调度器**(uvicorn 内守护线程):交易时段(9:30–11:30 / 13:00–15:00 CST)每分钟为有待触发条件单的账户跑 `check_triggers`;每日 15:35 后为所有账户落当日净值、并预热持仓/条件单个股与九大指数的 K线缓存。`ASHARE_WEB_SCHEDULER=0` 关闭;`GET /api/scheduler` 查状态。
  130. - **`ashare-sync` CLI**:立即跑一次每日结算+缓存预热;`--force` 跳过节假日判断。
  131. - **交易日历** `data/trade_calendar.json`:新浪交易日历(`calendar_trade_date_hist_sina`)本地缓存,7 天或越界自动刷新,取数失败回退旧文件;`GET /api/market-clock` 返回当前是否交易日,前端状态药丸节假日全天显示"休市"。
  132. - **行业分类** `data/industry.json`:申万一级行业(31 个,2021版)代码→行业映射,7 天自动刷新(6 小时节流),取数失败回退旧文件与打包快照 `data/industry.csv`;`GET /api/industries`、`POST /api/screen`(网页"选股"页)使用。
  133. - 已知限制:交易日历取数完全失败且无本地缓存时,盘中条件单检查退回到"周一~周五"规则——节假日盘中会用最近收盘价评估条件单(不会成交到不存在的行情)。
  134. ## Streamlit 看板(轻量旧版)
  135. ```powershell
  136. .venv\Scripts\python.exe -m streamlit run app.py # http://127.0.0.1:8501
  137. ```
  138. 四个页面:市场概览(指数/涨跌家数/涨停池/业绩日历)、个股行情
  139. (K线+资金流+财务+因子快照+公告)、模拟盘(买卖/条件单/持仓/订单)、
  140. 策略回测(指标+净值曲线+交易明细)。保留为轻量备用 UI。
  141. ## 给 agent 的任务示例
  142. - "茅台最近一年的日K线" → `get_kline("600519", "daily", adjust="qfq")`
  143. - "今天涨停的股票有哪些" → `get_limit_pool(pool="zt")`(近30个交易日)
  144. - "帮我模拟买入 100 股平安银行" → `paper_buy("000001", 100)`
  145. - "茅台跌到 1400 以下帮我买 100 股" → `paper_add_trigger("600519","buy",100,1400,"<=")`
  146. - "今年三季报谁的营收增速最快" → `get_earnings_calendar("20250930","yjbb")`
  147. - "茅台今天发了什么公告" → `get_announcements("600519")`
  148. - "平安银行的动量和波动率因子" → `get_factor_snapshot("000001")`
  149. - "用5/20均线在茅台回测2024年以来" → `run_backtest("600519", "ma_cross", {"fast":5,"slow":20}, "20240101")`
  150. - "茅台的利润表和主要财务指标" → `get_financial_statement` + `get_financial_abstract`
  151. ## 注意事项
  152. - **代码格式**:`"000001"` `"sz000001"` `"000001.SZ"` `"sh600000"` 都认;
  153. 6位裸码自动识别市场(6→沪、0/3→深、4/8/92→北)。
  154. - **指数 vs 股票**:`sh000001`=上证指数;裸 `"000001"`=平安银行。
  155. - **报价降级链**:东财快照 → 新浪1分钟线 → 新浪全市场快照 → 日线收盘;
  156. 响应里都标 `source`/`note`,兜底数据不是实时会注明。
  157. - **K线**:新浪优先、东财 `stock_zh_a_hist_em` 兜底(含限流冷却)。
  158. - **涨停池**:只覆盖最近约30个交易日(东财接口限制)。
  159. - **模拟盘**:纯模拟,不下真实订单。T+1 通过日期滚动实现。
  160. - **回测**:做多、lot取整、最小交易额死区跳过碎单(清仓除外)。
  161. ## 项目结构
  162. ```
  163. app.py # Streamlit 看板(轻量旧版)
  164. web/ # React+Vite 前端(npm run build -> web/dist)
  165. scripts/build_page.py # 生成 docs/index.html(GitHub Pages 快照页)
  166. docs/index.html # 静态展示页(每日自动刷新)
  167. .github/workflows/ # refresh-page.yml 定时重建
  168. src/ashare_mcp/
  169. ├── server.py # FastMCP 入口,34 个工具
  170. ├── config.py # env 配置、数据目录
  171. ├── utils.py # 代码/日期归一化、重采样
  172. ├── data/ # facade + akshare + tushare
  173. ├── trading/paper.py # 模拟盘引擎(SQLite 多账户,订单含 reason)
  174. ├── trading/accounts.py # 账户存储(paper.db:kind/model/arena + api_keys)
  175. ├── trading/arena.py # 竞技场排行榜与 Agent 详情
  176. ├── data/store.py # K线本地缓存(market.db)
  177. ├── backtest/engine.py # 日线回测器+参数扫描;portfolio.py 组合回测
  178. └── web/ # FastAPI 后端(/api + SPA 静态托管)
  179. data/paper.db # 模拟账户状态(gitignored)
  180. data/market.db # K线缓存(可随时删除)
  181. ```
  182. ## Disclaimer
  183. 仅供研究与模拟交易,不构成投资建议。数据来自新浪/东方财富/同花顺公开
  184. 接口,时效性与准确性以源站为准。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.