Metadata-Version: 2.4
Name: china-stock-analysis-mcp
Version: 0.1.0
Summary: Stock analysis MCP server with technical analysis and financial data tools. data source: tushare
Author-email: Bruce <bruce123asn@gmail.com>
License: MIT
Keywords: finance,mcp,stock,tushare
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-Python: >=3.11
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tushare>=1.4.25
Description-Content-Type: text/markdown

# Tushare MCP

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

## 功能特性

- **技术分析**：计算 MA、EMA、DMI、RSI、MACD、KDJ、布林带、ATR、OBV 等技术指标
- **财务数据**：获取股票利润表数据，包含营收、利润、费用、现金流等
- **智能解析**：支持股票代码（如 `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": {
    "tushare-mcp": {
      "command": "python",
      "args": ["D:/projects/tushare-mcp/mcp_server.py"]
    }
  }
}
```


## 可用工具

### 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="平安银行")
```

## 项目结构

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