Metadata-Version: 2.3
Name: china-stock-analysis-mcp
Version: 0.1.5
Summary: Stock analysis MCP server with technical analysis and financial data tools. data source: tushare
Keywords: tushare,stock,mcp,finance
Author: Bruce
Author-email: Bruce <bruce123asn@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: fastmcp>=2.12.4
Requires-Dist: uvicorn>=0.37.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: tushare>=1.4.25
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: py-candlekit
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# China-Stock-Analysis-MCP

基于 Tushare 的数据来源股票分析 MCP 服务器，提供技术分析和财务数据查询能力。

## 为什么选择本项目

对比纯爬虫实现的股票数据获取方案（如基于 [akshare](https://github.com/akfamily/akshare.git) 实现的 MCP），如果部署到云端对外提供MCP服务（如[讯飞星辰](https://mcp.xfyun.cn/mcp), [阿里百炼](https://bailian.console.aliyun.com/cn-beijing/#mcp-manage)）非常容易被反爬机制拦截，导致 MCP 失效。本项目基于 Tushare 的 Token 获取数据，使用官方 API 接口，可以接受更大的访问量，是更适合部署到云服务器上的股票数据 MCP 方案。

## 功能特性

- **技术分析**：计算 MA、EMA、DMI、RSI、MACD、KDJ、布林带、ATR、OBV 等技术指标
- **K线形态识别**：识别单根、两根、三根、五根K线组合形态（基于 py-candlekit 库）
- **财务数据**：获取股票利润表数据，包含营收、利润、费用、现金流等
- **智能解析**：支持不完整，不带交易所代号的股票代码（如 `002230`）或公司名称（如 `科大讯飞`）查询
- **前复权处理**：自动计算前复权价格，消除分红配送影响
- **多种运行模式**：支持 stdio 模式和 HTTP 流式模式
## 环境配置

```bash
# 1. 克隆项目
git clone <repo-url>
cd tushare-mcp

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 3. 安装依赖
pip install -e .

# 4. 配置 Tushare Token
# 在项目根目录创建 .env 文件，添加：
TUSHARE_TOKEN=你的Token
```

获取 Token：https://tushare.pro/user/token

## 快速开始

### 方式一：命令行运行

```bash
# stdio 模式（默认）
python -m china_stock_analysis_mcp

# HTTP 流式模式
python -m china_stock_analysis_mcp --streamable-http --host 0.0.0.0 --port 8081
```

### 方式二(推荐)：作为 MCP 工具使用

配置到 Claude Desktop 或其他 MCP 客户端：

```json
{
    "mcpServers":{
        "china-stock-analysis":{
            "command": "uvx",
            "args": ["china-stock-analysis-mcp"],
            "env":{
                "TUSHARE_TOKEN": "你的token"
            }
        }
    }
}
```


## 可用工具

### get_stock_technical_snapshot

获取股票技术分析快照，包含趋势、动量、波动率、成交量等指标，供 LLM 分析使用。

**参数：**

| 参数 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| ts_code | string | 是 | 可接受不带交易所的股票代码（如 `002230`）或公司名称（如 `科大讯飞`） | - |
| limit | number | 否 | 获取最近 N 根日线 | 100 |
| use_qfq | boolean | 否 | 是否使用前复权价格 | true |

**返回：** JSON 字符串，包含：

- **价格信息**：当前价、1日/5日/20日涨跌幅
- **趋势指标**：MA5、MA20、MA50、EMA12 与 EMA26 金叉/死叉状态
- **动量指标**：RSI14、MACD(DIF/DEA/MACD柱)、KDJ(K/D/J)
- **波动率指标**：布林带宽度、ATR14、价格相对于布林带位置
- **趋势强度**：ADX、+DI、-DI
- **成交量**：OBV 趋势、成交量/20日均量
- **信号标签**：RSI 超买/超卖、MACD 方向、KDJ 超买/超卖、均线多空排列、布林带突破、成交量信号、OBV 与价格背离

**示例：**

```python
# 查询平安银行技术分析
get_stock_technical_snapshot(ts_code="科大讯飞")
```

---

### get_income_data

获取股票利润表数据，包含近几期财务指标及同比变化趋势，供 LLM 分析使用。

**参数：**

| 参数 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| ts_code | string | 是 | 股票代码（如 `002230`）或公司名称（如 `科大讯飞`） | - |
| limit | number | 否 | 获取最近 N 期报告（约2年季报） | 10 |

**返回：** JSON 字符串，包含：

- **规模**：营业总收入、营业收入（单位：万元）
- **利润**：营业利润、归母净利润、EBIT、EBITDA、基本每股收益
- **利润率**：营业利润率、归母净利润率（%）
- **费用**：研发费用、销售费用、管理费用、财务费用（单位：万元）
- **费用率**：研发/销售/管理费用率（%）
- **风险**：资产减值损失、减值预警（减值损失>归母净利润10%）
- **同比增速**：营业收入同比、归母净利润同比、研发费用同比（%）

**说明：**
- 金额单位为万元，增速单位为%
- 同比基于去年同期同季度数据
- 只保留合并报表（report_type=1）
- 同一报告期保留最新且字段最完整的一条

**示例：**

```python
# 查询平安银行利润表
get_income_data(ts_code="科大讯飞")
```

---

### read_candles_type

识别 K 线形态（单根、两根、三根、五根组合），返回 JSON 字符串。

**参数：**

| 参数 | 类型 | 必填 | 说明 | 默认值 |
|------|------|------|------|--------|
| ts_code | string | 是 | 股票代码（如 `科大讯飞`）或公司名称（如 `科大讯飞`） | - |
| limit | number | 否 | 获取最近 N 根日线 | 100 |
| use_qfq | boolean | 否 | 是否使用前复权价格 | true |
| recent_n | number | 否 | 仅分析最近 N 根 K 线 | null |

**返回：** JSON 字符串，按形态类型分组：

```json
{
  "as_of_date": "2024-01-15",
  "single": {
    "date": "2024-01-15",
    "patterns": [{"name": "锤子线", "signal": "bullish", "strength": 4, ...}]
  },
  "double": {
    "dates": ["2024-01-14", "2024-01-15"],
    "patterns": [{"name": "看涨吞噬", "signal": "bullish", "strength": 5, ...}]
  },
  "triple": {
    "dates": ["2024-01-13", "2024-01-14", "2024-01-15"],
    "patterns": [{"name": "早晨之星", "signal": "bullish", "strength": 5, ...}]
  },
  "five": {
    "dates": ["2024-01-09", ..., "2024-01-15"],
    "patterns": [{"name": "上升三法", "signal": "bullish", "strength": 3, ...}]
  }
}
```

每个形态包含：
- **name**: 中文名称
- **name_en**: 英文名称
- **type**: 形态类型（single/double/triple/five）
- **signal**: 信号方向（bullish/bearish）
- **strength**: 信号强度（1-5）
- **description**: 形态描述


**支持的形态：**

- **单根形态**：十字星、锤子线、射击之星、光头光脚阳线/阴线、捉腰带阳线/阴线
- **两根形态**：看涨/看跌吞噬、刺穿形态、乌云盖顶、看涨/看跌孕十字、看涨/看跌踢脚线
- **三根形态**：早晨之星/十字星、黄昏之星/十字星、三白兵、三只乌鸦、三内部上涨、三外部上涨
- **五根形态**：上升三法、下降三法、垫高持有

> 基于 Steve Nison 的《Japanese Candlestick Charting Techniques》理论实现
**示例：**

```python
# 查询科大讯飞最近 50 根 K 线形态
read_candles_type(ts_code="科大讯飞", recent_n=50)
```

---

## 项目结构
```
tushare-mcp/
├── src/china_stock_analysis_mcp/
│   ├── __main__.py         # 入口，支持 stdio/HTTP 模式
│   ├── mcp_server.py       # MCP 工具定义
│   ├── technical_analysis.py
│   ├── stock_lookup.py
│   └── read_candles.py     # K线形态识别（基于 py-candlekit）
├── pyproject.toml
└── .env
```

## 依赖

- **[tushare](https://tushare.pro/)**：A股数据接口
- **fastmcp**：MCP 协议实现
- **pandas** / **numpy**：数据处理
- **[py-candlekit](https://github.com/zhirodadkhah/CandleKit.git)**：K线形态识别

## 注意事项

1. 首次使用需配置 Tushare Token
2. 股票代码缓存会自动更新（半年），可手动强制刷新
3. 前复权数据通过复权因子计算，可能与券商终端略有差异
4. 本项目仅供学习参考，不构成投资建议

## License

MIT