Metadata-Version: 2.3
Name: china-stock-analysis-mcp
Version: 0.1.4
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-Python: >=3.11
Description-Content-Type: text/markdown

# China-Stock-Analysis-MCP

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

## 功能特性

- **技术分析**：计算 MA、EMA、DMI、RSI、MACD、KDJ、布林带、ATR、OBV 等技术指标
- **K线形态识别**：识别单根、两根、三根K线组合形态（如锤子线、吞噬形态、早晨之星等）
- **财务数据**：获取股票利润表数据，包含营收、利润、费用、现金流等
- **智能解析**：支持股票代码（如 `000001.SZ`）或公司名称（如 `平安银行`）查询
- **前复权处理**：自动计算前复权价格，消除分红配送影响

## 环境配置

```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
python mcp_server.py
```

### 方式二(推荐)：作为 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 | 是 | 股票代码（如 `000001.SZ`）或公司名称（如 `平安银行`） | - |
| limit | number | 否 | 获取最近 N 根日线 | 200 |
| 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 | 是 | 股票代码（如 `000001.SZ`）或公司名称（如 `平安银行`） | - |
| 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 | 是 | 股票代码（如 `000001.SZ`）或公司名称（如 `平安银行`） | - |
| limit | number | 否 | 获取最近 N 根日线 | 200 |
| use_qfq | boolean | 否 | 是否使用前复权价格 | true |
| recent_n | number | 否 | 仅分析最近 N 根 K 线 | null |

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

- **count**: 分析的 K 线根数
- **candles**: K 线列表，每根 K 线包含：
  - **date**: 日期
  - **open/high/low/close**: 开高低收价格
  - **patterns**: 识别出的形态列表，每个形态包含：
    - **name**: 中文名称（如 "锤子线"）
    - **name_en**: 英文名称（如 "Hammer"）
    - **type**: 形态类型（single/double/triple）
    - **signal**: 信号方向（bullish/bearish/neutral）
    - **strength**: 信号强度（1-5）
    - **description**: 形态描述

**支持的形态：**

- **单根形态**：光头光脚阳线/阴线、大阳线/大阴线、十字星系列（墓碑/蜻蜓/长腿）、纺锤线、锤子线、上吊线、射击之星、倒锤线、捉腰带线
- **两根形态**：看涨/看跌吞噬、刺穿形态、乌云盖顶、看涨/看跌孕线、看涨/看跌孕十字、平头底部/顶部、看涨/看跌分离线、看涨/看跌踢脚线
- **三根形态**：早晨之星/十字星、黄昏之星/十字星、三白兵、三只乌鸦、三内部上涨/下跌、三外部上涨/下跌、弃婴看涨/看跌、上升/下降三法

**示例：**

```python
# 查询平安银行最近 50 根 K 线形态
read_candles_type(ts_code="平安银行", recent_n=50)
```

## 项目结构

```
tushare-mcp/
├── mcp_server.py          # MCP 服务器入口，定义工具
├── technical_analysis.py  # 技术分析类
├── stock_lookup.py        # 股票代码查询与缓存
├── main.py                # 独立运行示例
├── pyproject.toml         # 项目配置
└── .env                   # 环境变量（Token）
```

## 依赖

- **mcp[cli]**：MCP 协议实现
- **tushare**：A股数据接口
- **pandas**：数据处理
- **numpy**：数值计算
- **python-dotenv**：环境变量管理

## 注意事项

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

## License

MIT