Skip to content
Back to search

stock-mcp

专业的金融市场数据 MCP 服务器 - 支持A股/美股/加密货币,原生 MCP 协议,AI Agent 友好

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Install

i

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 · 597 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Stock MCP
  2. <div align="center">
  3. **[English](#english) | 中文**
  4. 开源金融数据 MCP / HTTP 服务,面向 AI Agent、量化脚本和普通后端集成。
  5. </div>
  6. ## 中文
  7. ### 这是什么
  8. `stock-mcp` 是一个开源金融数据服务,提供两套对外接口:
  9. - `MCP`:给 Claude Desktop、Cursor、DeerFlow、各类 Agent 使用
  10. - `HTTP API`:给普通后端、脚本和服务直接调用
  11. 它的定位不是“给投资建议”,而是提供:
  12. - 稳定的数据源接入
  13. - 标准化的金融工具能力
  14. - 适合 Agent 使用的 MCP tool / artifact 输出
  15. - 适合代码执行工作流的 CSV / JSON 数据导出
  16. ### 一键启动
  17. 如果你只是想先把服务跑起来,最短路径就是:
  18. ```bash
  19. git clone https://github.com/yourusername/stock-mcp.git
  20. cd stock-mcp
  21. cp .env.example .env
  22. docker compose up -d --build
  23. ```
  24. 启动后默认可访问:
  25. - `http://127.0.0.1:9898/health`
  26. - `http://127.0.0.1:9898/docs`
  27. - `http://127.0.0.1:9898/mcp`
  28. 默认 Docker 栈会一起启动:
  29. - `stock-mcp`
  30. - `redis`
  31. - `postgres`
  32. 默认端口:
  33. - `stock-mcp`: `127.0.0.1:9898`
  34. - `postgres`: `127.0.0.1:15432`
  35. 说明:
  36. - `15432` 是为了避免占用你本机已有的 `5432`
  37. - 容器内部仍然使用 `postgres:5432`
  38. - 如果你想修改宿主机映射端口,改 `DOCKER_POSTGRES_PORT` 即可
  39. ### 核心功能
  40. #### 1. 市场数据
  41. - A 股、美股、ETF、指数、加密资产行情
  42. - 日线 / 分时 / K 线数据
  43. - 多市场 ticker 解析与标准化
  44. - 多数据源回退
  45. #### 2. 技术分析
  46. - RSI、MACD、均线、布林带等常见指标
  47. - K 线形态识别
  48. - 支撑 / 压力位分析
  49. - 趋势与动量辅助分析
  50. #### 3. 基本面与研究
  51. - 估值与基础财务指标
  52. - 美股宏观和行业研究工具
  53. - 基于 Tavily 的统一新闻检索
  54. - 资金流与筹码分布
  55. #### 4. 公告与文档
  56. - SEC / EDGAR filings
  57. - A 股公告处理
  58. - 文档 chunk / markdown / 结构化提取
  59. #### 5. Agent / Code Workflow 友好能力
  60. - MCP tools 统一注册
  61. - MCP artifact 减载,避免把大 blob 直接塞进模型上下文
  62. - `code-export` HTTP 接口,可直接导出 CSV / JSON 给代码执行型 agent
  63. ### 支持的主要数据源
  64. 国内源:
  65. - `Tushare`
  66. - `Akshare`
  67. - `Baostock`
  68. 国外源:
  69. - `Yahoo / yfinance`
  70. - `Finnhub`
  71. - `Alpha Vantage`
  72. - `Twelve Data`
  73. - `FRED`
  74. - `CCXT`
  75. - `Crypto`
  76. - `EDGAR`
  77. ### HTTP API 能做什么
  78. 当前 HTTP 路由主要分为这些组:
  79. - `/api/v1/market/*`
  80. - 行情、K 线、技术指标、市场数据查询
  81. - `/api/v1/fundamental/*`
  82. - 基本面与估值
  83. - `/api/v1/money-flow/*`
  84. - 资金流分析
  85. - `/api/v1/news/*`
  86. - 统一新闻检索与个股新闻搜索
  87. - `/api/v1/filings/*`
  88. - SEC / A 股公告与文档处理
  89. - `/api/v1/code-export/*`
  90. - 面向代码执行工作流的数据导出
  91. - `/health`
  92. - 健康检查
  93. - `/docs` / `/redoc`
  94. - OpenAPI 文档
  95. 也就是说,这个项目不是只有 MCP。
  96. 如果你不打算接 MCP 客户端,完全可以只把它当普通 HTTP 服务来用。
  97. ### MCP 能做什么
  98. MCP 侧会把这些能力暴露成 tools,主要对应:
  99. - 行情和资产查询
  100. - 技术分析
  101. - 基本面与行业研究
  102. - 新闻与事件
  103. - 当前统一走 Tavily 检索,不再保留 adapter 原生新闻分支
  104. - 资金流与筹码
  105. - 公告与文档处理
  106. MCP 入口:
  107. - `POST /mcp`
  108. 适用场景:
  109. - Claude Desktop
  110. - Cursor
  111. - DeerFlow
  112. - 其他支持 MCP 的 Agent 平台
  113. ### 大体架构
  114. ```text
  115. +-----------------------------+
  116. | MCP Clients / HTTP Apps |
  117. | Claude / Cursor / Backends |
  118. +--------------+--------------+
  119. |
  120. v
  121. +-----------------------+
  122. | Thin Transports |
  123. | HTTP / MCP / Docs |
  124. +-----------+-----------+
  125. |
  126. v
  127. +-----------------------+
  128. | Runtime |
  129. | auth / proxy / health |
  130. | lifecycle / registry |
  131. +-----------+-----------+
  132. |
  133. +---------------+----------------+
  134. | |
  135. v v
  136. Capability Plugins Provider Plugins
  137. market / filings / news tushare / yahoo / edgar
  138. money_flow / code_export finnhub / fred / akshare
  139. | |
  140. +---------------+----------------+
  141. |
  142. v
  143. Redis / Postgres
  144. ```
  145. 职责分层大致是:
  146. - `src/server/runtime/`
  147. - 稳定骨架:配置、鉴权、代理策略、provider/capability registry、生命周期、健康状态
  148. - `src/server/capabilities/`
  149. - 业务能力插件:每个能力自带 `plugin / service / http / mcp / schema`
  150. - `src/server/providers/`
  151. - 数据源插件:每个 provider 声明自己支持的 contract
  152. - `src/server/transports/`
  153. - 薄入口:HTTP / MCP 只负责协议适配,不承载业务判断
  154. - `src/server/domain/`
  155. - 保留 provider 路由、符号解析、部分领域服务等底层实现;不再作为新增能力入口
  156. 当前重构方向是:
  157. - 不再围绕一个大而全的 `BaseDataAdapter` 扩展
  158. - 不再让 route / tool / service 三处并行增长
  159. - 新能力优先通过 capability plugin 接入
  160. - 新数据源优先通过 provider plugin + contract 接入
  161. ### 认证模式
  162. `stock-mcp` 支持三档认证:
  163. #### 1. `none`
  164. - 本地开发 / 开源试用默认模式
  165. - 不做鉴权
  166. - 推荐只监听 `127.0.0.1`
  167. #### 2. `token`
  168. - 适合个人部署或内网服务
  169. - 所有受保护路径统一使用静态 Bearer token
  170. #### 3. `jwt`
  171. - 适合生产和平台集成
  172. - 基于 `JWTVerifier + OIDC / JWKS`
  173. - 不绑定 Keycloak,兼容任意 OIDC/JWT IdP
  174. 在 `token` 和 `jwt` 模式下:
  175. - `/health` 匿名开放
  176. - `/mcp`、`/api/v1/*`、`/docs`、`/redoc`、`/openapi.json`、`/` 需要 Bearer token
  177. ### 代理规则
  178. 当前项目采用“国外源显式代理,国内源直连”的边界:
  179. 显式走代理:
  180. - `Yahoo / yfinance`
  181. - `Finnhub`
  182. - `Futures`
  183. - `Alpha Vantage`
  184. - `Twelve Data`
  185. - `FRED`
  186. - `CCXT`
  187. - `Crypto`
  188. - `EDGAR`
  189. 保持直连:
  190. - `Tushare`
  191. - `Akshare`
  192. - `Baostock`
  193. Docker 下默认会把:
  194. - `PROXY_HOST`
  195. 覆盖成:
  196. - `host.docker.internal`
  197. 这样容器里的国外源可以访问宿主机代理。
  198. 如果你的代理不在宿主机上,可以改:
  199. - `DOCKER_PROXY_HOST`
  200. ### 本地运行方式
  201. #### 1. uv 本地运行
  202. ```bash
  203. uv sync --dev
  204. cp .env.example .env
  205. export STOCK_MCP_AUTH_MODE=none
  206. uv run python -m uvicorn src.server.app:app --host 127.0.0.1 --port 9898
  207. ```
  208. #### 2. Docker Compose 运行
  209. ```bash
  210. cp .env.example .env
  211. docker compose up -d --build
  212. ```
  213. 如果你切换过数据库配置或旧卷和当前配置不一致,建议首次执行:
  214. ```bash
  215. docker compose down -v
  216. docker compose up -d --build
  217. ```
  218. #### 3. stdio MCP
  219. ```bash
  220. uv run python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"
  221. ```
  222. ### 调用示例
  223. #### HTTP API 示例
  224. ```bash
  225. curl -X POST http://127.0.0.1:9898/api/v1/technical/indicators/calculate \
  226. -H "Content-Type: application/json" \
  227. -d '{
  228. "symbol": "SSE:600519",
  229. "period": "6mo",
  230. "interval": "1d"
  231. }'
  232. ```
  233. #### MCP 示例
  234. ```bash
  235. curl -X POST http://127.0.0.1:9898/mcp \
  236. -H "Content-Type: application/json" \
  237. -d '{
  238. "jsonrpc": "2.0",
  239. "method": "tools/call",
  240. "params": {
  241. "name": "get_kline_data",
  242. "arguments": {
  243. "symbol": "SSE:600519"
  244. }
  245. },
  246. "id": "1"
  247. }'
  248. ```
  249. ### 常用环境变量
  250. 推荐优先关注这些变量:
  251. - `STOCK_MCP_AUTH_MODE=none|token|jwt`
  252. - `STOCK_MCP_STATIC_BEARER_TOKEN`
  253. - `MCP_HOST`, `MCP_PORT`
  254. - `DOCKER_POSTGRES_PORT`, `DOCKER_POSTGRES_USER`, `DOCKER_POSTGRES_PASSWORD`, `DOCKER_POSTGRES_DB`
  255. - `PROXY_ENABLED`, `PROXY_HOST`, `PROXY_PORT`
  256. - `DOCKER_PROXY_HOST`
  257. - `TUSHARE_ENABLED`, `TUSHARE_TOKEN`, `TUSHARE_HTTP_URL`
  258. - `FINNHUB_ENABLED`, `FINNHUB_API_KEY`
  259. - `TAVILY_API_KEY`
  260. - `SECURITY_MASTER_BACKEND`, `SECURITY_MASTER_SQLITE_PATH`
  261. - `DATABASE_URL`
  262. - `MCP_TOOL_TIMEOUT_SECONDS`, `PROVIDER_CALL_TIMEOUT_SECONDS`
  263. 完整示例见:
  264. - [`/Users/huweihua/java/qiuzhao/stock-mcp/.env.example`](/Users/huweihua/java/qiuzhao/stock-mcp/.env.example)
  265. ### 测试
  266. ```bash
  267. uv run pytest
  268. ```
  269. ### 项目目录
  270. ```text
  271. stock-mcp/
  272. ├── src/server/api/ # FastAPI HTTP 路由
  273. ├── src/server/mcp/ # MCP server 与 tools
  274. ├── src/server/domain/ # adapter / service / router
  275. ├── src/server/infrastructure/ # Redis / Postgres / 外部连接
  276. ├── src/server/core/ # 配置、依赖注入、启动流程
  277. ├── docs/ # 补充文档
  278. └── tests/ # pytest 测试
  279. ```
  280. ### License
  281. MIT
  282. ---
  283. ## English
  284. ### What it is
  285. `stock-mcp` is an open-source financial data service with two public interfaces:
  286. - `MCP` for AI agents such as Claude Desktop, Cursor, and DeerFlow
  287. - `HTTP API` for regular backends, scripts, and service integrations
  288. It is designed to provide reliable market data and analysis tools, not investment advice.
  289. ### One-command start
  290. ```bash
  291. git clone https://github.com/yourusername/stock-mcp.git
  292. cd stock-mcp
  293. cp .env.example .env
  294. docker compose up -d --build
  295. ```
  296. Default endpoints:
  297. - `http://127.0.0.1:9898/health`
  298. - `http://127.0.0.1:9898/docs`
  299. - `http://127.0.0.1:9898/mcp`
  300. Default services:
  301. - `stock-mcp`
  302. - `redis`
  303. - `postgres`
  304. Default host ports:
  305. - `stock-mcp`: `127.0.0.1:9898`
  306. - `postgres`: `127.0.0.1:15432`
  307. ### Main capabilities
  308. - Market data across A-shares, US equities, ETFs, indices, and crypto
  309. - Technical indicators such as RSI, MACD, moving averages, support/resistance, candlestick patterns
  310. - Fundamentals, money flow, chip analysis, filings, and Tavily-backed news search
  311. - Agent-friendly MCP tools and code-export endpoints
  312. ### Public interfaces
  313. HTTP route groups:
  314. - `/api/v1/market/*`
  315. - `/api/v1/technical/*`
  316. - `/api/v1/fundamental/*`
  317. - `/api/v1/money-flow/*`
  318. - `/api/v1/news/*`
  319. - `/api/v1/filings/*`
  320. - `/api/v1/code-export/*`
  321. - `/health`
  322. - `/docs` / `/redoc`
  323. MCP endpoint:
  324. - `/mcp`
  325. ### Architecture
  326. ```text
  327. MCP clients / HTTP apps
  328. |
  329. v
  330. Thin transports (HTTP / MCP)
  331. |
  332. v
  333. Runtime substrate
  334. auth / proxy / lifecycle / registries
  335. |
  336. v
  337. Capability plugins <-> Provider plugins
  338. |
  339. v
  340. Redis / Postgres
  341. ```
  342. The runtime/plugin refactor is complete. Internal layering:
  343. - `src/server/runtime/`
  344. - stable substrate for auth, proxy policy, provider/capability registry, lifecycle, and health
  345. - `src/server/capabilities/`
  346. - business capability plugins such as `market`, `filings`, `news`, `money_flow`, `code_export`
  347. - `src/server/providers/`
  348. - provider plugins declaring which contracts they implement
  349. - `src/server/transports/`
  350. - thin HTTP/MCP protocol adapters
  351. - `src/server/domain/`
  352. - symbol resolution and lower-level domain services behind the runtime/provider facade surface; not an extension entrypoint
  353. Only heavy internal logic remains in `src/server/domain/services/`; lightweight capabilities stay capability-local by default.
  354. Extension rules:
  355. - new capabilities should be added as capability plugins
  356. - new data sources should be added as provider plugins
  357. - HTTP and MCP surfaces are composed from the same capability registry
  358. ### Authentication modes
  359. - `none`: local development and quick trial
  360. - `token`: static Bearer token for personal or intranet deployment
  361. - `jwt`: production mode using OIDC / JWKS compatible JWT verification
  362. ### Proxy boundary
  363. Explicit proxy for foreign providers:
  364. - `Yahoo / yfinance`
  365. - `Finnhub`
  366. - `Futures`
  367. - `Alpha Vantage`
  368. - `Twelve Data`
  369. - `FRED`
  370. - `CCXT`
  371. - `Crypto`
  372. - `EDGAR`
  373. Direct connection for domestic providers:
  374. - `Tushare`
  375. - `Akshare`
  376. - `Baostock`
  377. In Docker mode, `PROXY_HOST` is overridden to `host.docker.internal` by default. Override it with
  378. `DOCKER_PROXY_HOST` when needed.
  379. ### Run modes
  380. #### Local uv
  381. ```bash
  382. uv sync --dev
  383. cp .env.example .env
  384. export STOCK_MCP_AUTH_MODE=none
  385. uv run python -m uvicorn src.server.app:app --host 127.0.0.1 --port 9898
  386. ```
  387. #### Docker Compose
  388. ```bash
  389. cp .env.example .env
  390. docker compose up -d --build
  391. ```
  392. If you previously used different database settings or stale volumes exist:
  393. ```bash
  394. docker compose down -v
  395. docker compose up -d --build
  396. ```
  397. #### stdio MCP
  398. ```bash
  399. uv run python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"
  400. ```
  401. ### Example calls
  402. HTTP:
  403. ```bash
  404. curl -X POST http://127.0.0.1:9898/api/v1/technical/indicators/calculate \
  405. -H "Content-Type: application/json" \
  406. -d '{
  407. "symbol": "SSE:600519",
  408. "period": "6mo",
  409. "interval": "1d"
  410. }'
  411. ```
  412. MCP:
  413. ```bash
  414. curl -X POST http://127.0.0.1:9898/mcp \
  415. -H "Content-Type: application/json" \
  416. -d '{
  417. "jsonrpc": "2.0",
  418. "method": "tools/call",
  419. "params": {
  420. "name": "get_kline_data",
  421. "arguments": {
  422. "symbol": "SSE:600519"
  423. }
  424. },
  425. "id": "1"
  426. }'
  427. ```
  428. ### Repository layout
  429. ```text
  430. stock-mcp/
  431. ├── src/server/api/
  432. ├── src/server/mcp/
  433. ├── src/server/domain/
  434. ├── src/server/infrastructure/
  435. ├── src/server/core/
  436. ├── docs/
  437. └── tests/
  438. ```
  439. ### License
  440. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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