# Stock MCP

<div align="center">

**[English](#english) | 中文**

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

</div>

## 中文

### 这是什么

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

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

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

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

### 一键启动

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

```bash
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 平台

### 大体架构

```text
                +-----------------------------+
                |    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 本地运行

```bash
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 运行

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

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

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

#### 3. stdio MCP

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

### 调用示例

#### HTTP API 示例

```bash
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 示例

```bash
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`](/Users/huweihua/java/qiuzhao/stock-mcp/.env.example)

### 测试

```bash
uv run pytest
```

### 项目目录

```text
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

```bash
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

```text
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

```bash
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

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

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

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

#### stdio MCP

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

### Example calls

HTTP:

```bash
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:

```bash
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

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

### License

MIT