# research-report-mcp-server

**Repository Path**: handaas/research-report-mcp-server

## Basic Information

- **Project Name**: research-report-mcp-server
- **Description**: HandaaS 行业研报 MCP Server — 研报搜索/机构筛选/行业筛选/报告详情/来源链接
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-21
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 行业研报检索

[该MCP服务提供行业研报、公司研究、宏观策略和主题报告的检索与详情查询功能。](https://www.handaas.com/)


## 主要功能

- 🔍 研报标题关键词搜索
- 🏢 发布机构筛选
- 🏭 研究行业筛选
- 📑 报告类型筛选
- 📅 发布时间区间筛选
- 🔗 研报详情和来源链接查询

## 环境要求

- Python 3.10+
- 依赖包：python-dotenv, requests, mcp

## 本地快速启动

### 1. 克隆项目
```bash
git clone https://github.com/handaas/research-report-mcp-server
cd research-report-mcp-server
```

### 2. 创建虚拟环境&安装依赖

```bash
python -m venv mcp_env && source mcp_env/bin/activate
pip install -r requirements.txt
```

### 3. 环境配置

复制环境变量模板并配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置以下环境变量：

```env
INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30
```

### 4. streamable-http启动服务

```bash
python server/mcp_server.py streamable-http
```

服务将在 `http://localhost:8000` 启动，MCP 地址为 `http://127.0.0.1:8000/mcp`。

#### 支持启动方式 stdio 或 sse 或 streamable-http

### 5. Cursor / Cherry Studio MCP配置

```json
{
  "mcpServers": {
    "research-report-mcp-server": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

## STDIO版安装部署

### 设置Cursor / Cherry Studio MCP配置

```json
{
  "mcpServers": {
    "research-report-mcp-server": {
      "command": "uv",
      "args": ["run", "mcp", "run", "{workdir}/server/mcp_server.py"],
      "env": {
        "PATH": "{workdir}/mcp_env/bin:$PATH",
        "PYTHONPATH": "{workdir}/mcp_env",
        "INTEGRATOR_ID": "your_integrator_id",
        "SECRET_ID": "your_secret_id",
        "SECRET_KEY": "your_secret_key"
      }
    }
  }
}
```

## 使用官方Remote服务

### 1. 直接设置Cursor / Cherry Studio MCP配置

```json
{
  "mcpServers": {
    "research-report-mcp-server":{
      "type": "streamableHttp",
      "url": "https://mcp.handaas.com/research_report/research_report_bigdata?token={token}"
      }
  }
}
```

### 注意：integrator_id、secret_id、secret_key及token需要登录 https://www.handaas.com/ 进行注册开通平台获取


## 可用工具

### 1. research_report_search
**功能**: 行业研报搜索

**参数**:
- `rpKeyword` (可选): 研报标题关键词，支持模糊搜索
- `rpOrgName` (可选): 发布机构全称或简称
- `rpCalIndustryList` (可选): 研究行业
- `rpType` (可选): 报告类型
- `rpPublishDateStart` / `rpPublishDateEnd` (可选): 发布日期区间，格式YYYY-MM-DD
- `pageIndex` (可选): 页码，从1开始
- `pageSize` (可选): 每页条数，默认10，最大10

**返回值**:
- `total`: 符合条件的研报总数
- `resultList`: 研报结果列表
  - `reportId`: 研报ID，供详情查询使用
  - `rpName`: 研报名称
  - `rpCover`: 封面图URL
  - `rpOrgName`: 机构全称
  - `rpOrgShortName`: 机构简称
  - `nameId`: 机构主体ID
  - `rpPublishDate`: 发布日期
  - `rpCalIndustryList`: 行业分类
  - `rpType`: 研报类型

### 2. research_report_detail
**功能**: 行业研报详情查询

**参数**:
- `reportId` (必需): 必须使用研报搜索返回的 `reportId`

**返回值**:
- `total`: 命中数量，通常为1
- `resultList`: 研报详情列表
  - `rpName`: 研报名称
  - `rpOrgName`: 机构全称
  - `rpOrgShortName`: 机构简称
  - `nameId`: 机构主体ID
  - `rpPublishDate`: 发布日期
  - `rpCalIndustryList`: 行业分类
  - `rpType`: 研报类型
  - `rpUrl`: 研报来源链接
  - `rpPdf`: PDF地址元数据

## 使用注意事项

1. **研报ID要求**: 详情查询必须使用研报搜索结果中的 `reportId`。
2. **日期校验**: 发布起始日期不能晚于截止日期。
3. **API限制**: 分页查询一页最多获取10条数据。
4. **文件边界**: Tool只返回来源链接元数据，不打开、购买、下载或解析研报文件。
5. **内容立场**: 研报观点属于原发布机构，不代表MCP服务立场。

## 使用提问示例

### research_report_search (行业研报搜索)
1. 搜索2026年发布的人工智能行业研报
2. 查询某研究机构发布的新能源研报
3. 查找最近一年发布的宏观策略报告

### research_report_detail (行业研报详情查询)
1. 查看刚才研报的发布机构和发布日期
2. 获取该研报的行业分类和来源链接
3. 查询这份研报的完整元数据信息

## 测试验证

```bash
python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -v
```

当前服务包含 7 个离线单元测试。真实接口验证需在本地 `.env` 配置有效凭据后执行，测试输出不得提交真实业务响应或凭据。