Stock MCP

English | 中文

开源金融数据 MCP / HTTP 服务，面向 AI Agent、量化脚本和普通后端集成。

中文

这是什么

stock-mcp 是一个开源金融数据服务，提供两套对外接口：

MCP：给 Claude Desktop、Cursor、DeerFlow、各类 Agent 使用
HTTP API：给普通后端、脚本和服务直接调用

它的定位不是“给投资建议”，而是提供：

稳定的数据源接入
标准化的金融工具能力
适合 Agent 使用的 MCP tool / artifact 输出
适合代码执行工作流的 CSV / JSON 数据导出

一键启动

如果你只是想先把服务跑起来，最短路径就是：

git clone https://github.com/yourusername/stock-mcp.git
cd stock-mcp
cp .env.example .env
docker compose up -d --build

启动后默认可访问：

http://127.0.0.1:9898/health
http://127.0.0.1:9898/docs
http://127.0.0.1:9898/mcp

默认 Docker 栈会一起启动：

stock-mcp
redis
postgres

默认端口：

stock-mcp: 127.0.0.1:9898
postgres: 127.0.0.1:15432

说明：

15432 是为了避免占用你本机已有的 5432
容器内部仍然使用 postgres:5432
如果你想修改宿主机映射端口，改 DOCKER_POSTGRES_PORT 即可

核心功能

1. 市场数据

A 股、美股、ETF、指数、加密资产行情
日线 / 分时 / K 线数据
多市场 ticker 解析与标准化
多数据源回退

2. 技术分析

RSI、MACD、均线、布林带等常见指标
K 线形态识别
支撑 / 压力位分析
趋势与动量辅助分析

3. 基本面与研究

估值与基础财务指标
美股宏观和行业研究工具
基于 Tavily 的统一新闻检索
资金流与筹码分布

4. 公告与文档

SEC / EDGAR filings
A 股公告处理
文档 chunk / markdown / 结构化提取

5. Agent / Code Workflow 友好能力

MCP tools 统一注册
MCP artifact 减载，避免把大 blob 直接塞进模型上下文
code-export HTTP 接口，可直接导出 CSV / JSON 给代码执行型 agent

支持的主要数据源

国内源：

Tushare
Akshare
Baostock

国外源：

Yahoo / yfinance
Finnhub
Alpha Vantage
Twelve Data
FRED
CCXT
Crypto
EDGAR

HTTP API 能做什么

当前 HTTP 路由主要分为这些组：

/api/v1/market/*
- 行情、K 线、技术指标、市场数据查询
/api/v1/fundamental/*
- 基本面与估值
/api/v1/money-flow/*
- 资金流分析
/api/v1/news/*
- 统一新闻检索与个股新闻搜索
/api/v1/filings/*
- SEC / A 股公告与文档处理
/api/v1/code-export/*
- 面向代码执行工作流的数据导出
/health
- 健康检查
/docs / /redoc
- OpenAPI 文档

也就是说，这个项目不是只有 MCP。

如果你不打算接 MCP 客户端，完全可以只把它当普通 HTTP 服务来用。

MCP 能做什么

MCP 侧会把这些能力暴露成 tools，主要对应：

行情和资产查询
技术分析
基本面与行业研究
新闻与事件
- 当前统一走 Tavily 检索，不再保留 adapter 原生新闻分支
资金流与筹码
公告与文档处理

MCP 入口：

POST /mcp

适用场景：

Claude Desktop
Cursor
DeerFlow
其他支持 MCP 的 Agent 平台

大体架构

                +-----------------------------+
                |    MCP Clients / HTTP Apps  |
                | Claude / Cursor / Backends  |
                +--------------+--------------+
                               |
                               v
                    +-----------------------+
                    |   Thin Transports     |
                    |  HTTP / MCP / Docs    |
                    +-----------+-----------+
                                |
                                v
                    +-----------------------+
                    |        Runtime        |
                    | auth / proxy / health |
                    | lifecycle / registry  |
                    +-----------+-----------+
                                |
                +---------------+----------------+
                |                                |
                v                                v
        Capability Plugins                Provider Plugins
      market / filings / news         tushare / yahoo / edgar
      money_flow / code_export        finnhub / fred / akshare
                |                                |
                +---------------+----------------+
                                |
                                v
                           Redis / Postgres

职责分层大致是：

src/server/runtime/
- 稳定骨架：配置、鉴权、代理策略、provider/capability registry、生命周期、健康状态
src/server/capabilities/
- 业务能力插件：每个能力自带 plugin / service / http / mcp / schema
src/server/providers/
- 数据源插件：每个 provider 声明自己支持的 contract
src/server/transports/
- 薄入口：HTTP / MCP 只负责协议适配，不承载业务判断
src/server/domain/
- 保留 provider 路由、符号解析、部分领域服务等底层实现；不再作为新增能力入口

当前重构方向是：

不再围绕一个大而全的 BaseDataAdapter 扩展
不再让 route / tool / service 三处并行增长
新能力优先通过 capability plugin 接入
新数据源优先通过 provider plugin + contract 接入

认证模式

stock-mcp 支持三档认证：

1. `none`

本地开发 / 开源试用默认模式
不做鉴权
推荐只监听 127.0.0.1

2. `token`

适合个人部署或内网服务
所有受保护路径统一使用静态 Bearer token

3. `jwt`

适合生产和平台集成
基于 JWTVerifier + OIDC / JWKS
不绑定 Keycloak，兼容任意 OIDC/JWT IdP

在 token 和 jwt 模式下：

/health 匿名开放
/mcp、/api/v1/*、/docs、/redoc、/openapi.json、/ 需要 Bearer token

代理规则

当前项目采用“国外源显式代理，国内源直连”的边界：

显式走代理：

Yahoo / yfinance
Finnhub
Futures
Alpha Vantage
Twelve Data
FRED
CCXT
Crypto
EDGAR

保持直连：

Tushare
Akshare
Baostock

Docker 下默认会把：

PROXY_HOST

覆盖成：

host.docker.internal

这样容器里的国外源可以访问宿主机代理。
如果你的代理不在宿主机上，可以改：

DOCKER_PROXY_HOST

本地运行方式

1. uv 本地运行

uv sync --dev
cp .env.example .env

export STOCK_MCP_AUTH_MODE=none
uv run python -m uvicorn src.server.app:app --host 127.0.0.1 --port 9898

2. Docker Compose 运行

cp .env.example .env
docker compose up -d --build

如果你切换过数据库配置或旧卷和当前配置不一致，建议首次执行：

docker compose down -v
docker compose up -d --build

3. stdio MCP

uv run python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"

调用示例

HTTP API 示例

curl -X POST http://127.0.0.1:9898/api/v1/technical/indicators/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SSE:600519",
    "period": "6mo",
    "interval": "1d"
  }'

MCP 示例

curl -X POST http://127.0.0.1:9898/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_kline_data",
      "arguments": {
        "symbol": "SSE:600519"
      }
    },
    "id": "1"
  }'

常用环境变量

推荐优先关注这些变量：

STOCK_MCP_AUTH_MODE=none|token|jwt
STOCK_MCP_STATIC_BEARER_TOKEN
MCP_HOST, MCP_PORT
DOCKER_POSTGRES_PORT, DOCKER_POSTGRES_USER, DOCKER_POSTGRES_PASSWORD, DOCKER_POSTGRES_DB
PROXY_ENABLED, PROXY_HOST, PROXY_PORT
DOCKER_PROXY_HOST
TUSHARE_ENABLED, TUSHARE_TOKEN, TUSHARE_HTTP_URL
FINNHUB_ENABLED, FINNHUB_API_KEY
TAVILY_API_KEY
SECURITY_MASTER_BACKEND, SECURITY_MASTER_SQLITE_PATH
DATABASE_URL
MCP_TOOL_TIMEOUT_SECONDS, PROVIDER_CALL_TIMEOUT_SECONDS

完整示例见：

/Users/huweihua/java/qiuzhao/stock-mcp/.env.example

测试

uv run pytest

项目目录

stock-mcp/
├── src/server/api/             # FastAPI HTTP 路由
├── src/server/mcp/             # MCP server 与 tools
├── src/server/domain/          # adapter / service / router
├── src/server/infrastructure/  # Redis / Postgres / 外部连接
├── src/server/core/            # 配置、依赖注入、启动流程
├── docs/                       # 补充文档
└── tests/                      # pytest 测试

License

MIT

English

What it is

stock-mcp is an open-source financial data service with two public interfaces:

MCP for AI agents such as Claude Desktop, Cursor, and DeerFlow
HTTP API for regular backends, scripts, and service integrations

It is designed to provide reliable market data and analysis tools, not investment advice.

One-command start

git clone https://github.com/yourusername/stock-mcp.git
cd stock-mcp
cp .env.example .env
docker compose up -d --build

Default endpoints:

http://127.0.0.1:9898/health
http://127.0.0.1:9898/docs
http://127.0.0.1:9898/mcp

Default services:

stock-mcp
redis
postgres

Default host ports:

stock-mcp: 127.0.0.1:9898
postgres: 127.0.0.1:15432

Main capabilities

Market data across A-shares, US equities, ETFs, indices, and crypto
Technical indicators such as RSI, MACD, moving averages, support/resistance, candlestick patterns
Fundamentals, money flow, chip analysis, filings, and Tavily-backed news search
Agent-friendly MCP tools and code-export endpoints

Public interfaces

HTTP route groups:

/api/v1/market/*
/api/v1/technical/*
/api/v1/fundamental/*
/api/v1/money-flow/*
/api/v1/news/*
/api/v1/filings/*
/api/v1/code-export/*
/health
/docs / /redoc

MCP endpoint:

/mcp

Architecture

MCP clients / HTTP apps
          |
          v
  Thin transports (HTTP / MCP)
          |
          v
Runtime substrate
auth / proxy / lifecycle / registries
          |
          v
Capability plugins <-> Provider plugins
          |
          v
Redis / Postgres

The runtime/plugin refactor is complete. Internal layering:

src/server/runtime/
- stable substrate for auth, proxy policy, provider/capability registry, lifecycle, and health
src/server/capabilities/
- business capability plugins such as market, filings, news, money_flow, code_export
src/server/providers/
- provider plugins declaring which contracts they implement
src/server/transports/
- thin HTTP/MCP protocol adapters
src/server/domain/
- symbol resolution and lower-level domain services behind the runtime/provider facade surface; not an extension entrypoint

Only heavy internal logic remains in src/server/domain/services/; lightweight capabilities stay capability-local by default.

Extension rules:

new capabilities should be added as capability plugins
new data sources should be added as provider plugins
HTTP and MCP surfaces are composed from the same capability registry

Authentication modes

none: local development and quick trial
token: static Bearer token for personal or intranet deployment
jwt: production mode using OIDC / JWKS compatible JWT verification

Proxy boundary

Explicit proxy for foreign providers:

Yahoo / yfinance
Finnhub
Futures
Alpha Vantage
Twelve Data
FRED
CCXT
Crypto
EDGAR

Direct connection for domestic providers:

Tushare
Akshare
Baostock

In Docker mode, PROXY_HOST is overridden to host.docker.internal by default. Override it with DOCKER_PROXY_HOST when needed.

Run modes

Local uv

uv sync --dev
cp .env.example .env
export STOCK_MCP_AUTH_MODE=none
uv run python -m uvicorn src.server.app:app --host 127.0.0.1 --port 9898

Docker Compose

cp .env.example .env
docker compose up -d --build

If you previously used different database settings or stale volumes exist:

docker compose down -v
docker compose up -d --build

stdio MCP

uv run python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"

Example calls

HTTP:

curl -X POST http://127.0.0.1:9898/api/v1/technical/indicators/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SSE:600519",
    "period": "6mo",
    "interval": "1d"
  }'

MCP:

curl -X POST http://127.0.0.1:9898/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_kline_data",
      "arguments": {
        "symbol": "SSE:600519"
      }
    },
    "id": "1"
  }'

Repository layout

stock-mcp/
├── src/server/api/
├── src/server/mcp/
├── src/server/domain/
├── src/server/infrastructure/
├── src/server/core/
├── docs/
└── tests/

License

MIT

Stock ToolStock Tool

Stock MCP

中文

这是什么

一键启动

核心功能

1. 市场数据

2. 技术分析

3. 基本面与研究

4. 公告与文档

5. Agent / Code Workflow 友好能力

支持的主要数据源

HTTP API 能做什么

MCP 能做什么

大体架构

认证模式

1. none

2. token

3. jwt

代理规则

本地运行方式

1. uv 本地运行

2. Docker Compose 运行

3. stdio MCP

调用示例

HTTP API 示例

MCP 示例

常用环境变量

测试

项目目录

License

English

What it is

One-command start

Main capabilities

Public interfaces

Architecture

Authentication modes

Proxy boundary

Run modes

Local uv

Docker Compose

stdio MCP

Example calls

Repository layout

License

1. `none`

2. `token`

3. `jwt`