内容
# CSMAR MCP 服务器
[](LICENSE)
[](https://spec.modelcontextprotocol.io)
[](https://nodejs.org)
[](https://www.python.org)
国泰安（CSMAR）金融数据库的 Model Context Protocol (MCP) 服务器，支持在 Codex、Claude Code 等 MCP 客户端中直接访问 CSMAR 金融数据。
发布者：小红书博主：人生在路上
详细安装、配置和开源注意事项见 [使用说明.md](使用说明.md)。
## ✨ 功能特性
- **完整的 CSMAR 数据访问**：支持 240+ 个数据库，包括财务报表、股票交易、公司信息等
- **智能登录管理**：支持环境变量自动登录和令牌缓存
- **13 个 MCP 工具**：涵盖数据库探索、目录搜索、数据查询、预览和导出等功能
- **持久化 Python 进程**：复用 Python 会话，大幅提升性能
- **请求重试机制**：网络不稳定时自动重试
- **优雅关闭**：支持 SIGTERM/SIGINT 信号
- **健康检查**：随时查看服务状态
- **Python 中间层**：基于 CSMAR-PYTHON SDK 的稳定封装
- **配置简单**：支持 Codex、Claude Code 等 MCP 客户端集成
## 📋 前提条件
1. **CSMAR 账号**：有效的 CSMAR（国泰安）机构账号（个人或机构账号均可）
2. **Python 3.8+**：需要安装 CSMAR-PYTHON SDK 及其依赖
- 安装 Python 依赖：`pip install urllib3 websocket websocket_client pandas prettytable`
- 下载并安装 CSMAR-PYTHON SDK（从官网或联系 CSMAR 获取）
3. **Node.js 18+**：运行 MCP 服务器
4. **MCP 客户端**：Codex、Claude Code 或其他支持 MCP 的客户端
## 🚀 快速开始
### 1. 克隆项目
```bash
git clone <YOUR_GITHUB_REPO_URL>
cd Csmar-MCP-server
```
### 2. 安装依赖
```bash
# 安装Node.js依赖
npm install
# 安装Python依赖（CSMAR SDK所需）
pip install urllib3 websocket websocket_client pandas prettytable
# 安装CSMAR-PYTHON SDK
# 从CSMAR官网下载SDK压缩包，解压到Python的site-packages目录
# 或者按照官方文档安装：https://www.gtadata.com/products/csmar-api
```
### 3. 配置环境变量
在项目根目录创建 `.env` 文件：
```env
# CSMAR 配置
CSMAR_API_BASE=https://api.gtarsc.com
CSMAR_USERNAME=你的CSMAR用户名
CSMAR_PASSWORD=你的CSMAR密码
CSMAR_LANG=0 # 0=中文, 1=英文
```
> ⚠️ **安全提示**：请勿将 `.env` 文件提交到 Git！已配置 `.gitignore` 自动忽略。
### 4. 配置 Claude Code(包含Claude客户端和vscode扩展两种配置方式)
在 Claude Code 的配置文件中添加 MCP 服务器配置：
**Windows** (`%APPDATA%/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"csmar": {
"command": "node",
"args": ["C:\\path\\to\\Csmar-MCP-server\\src\\index.js"],
"env": {
"CSMAR_API_BASE": "https://api.gtarsc.com",
"CSMAR_USERNAME": "你的CSMAR用户名",
"CSMAR_PASSWORD": "你的CSMAR密码",
"CSMAR_LANG": "0"
}
}
}
}
```
**macOS/Linux** (`~/.config/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"csmar": {
"command": "node",
"args": ["/path/to/Csmar-MCP-server/src/index.js"],
"env": {
"CSMAR_API_BASE": "https://api.gtarsc.com",
"CSMAR_USERNAME": "你的CSMAR用户名",
"CSMAR_PASSWORD": "你的CSMAR密码",
"CSMAR_LANG": "0"
}
}
}
}
```
如果用户使用的是VS code中的Claude code扩展，配置方式如下：
配置env文件之后，修改Claude Code MCP配置
VSCode 中 Claude Code 的 MCP 配置文件在：
```code
%APPDATA%/Code/User/globalStorage/saoudval.claude-code/mcp.json
```
或者在 VSCode 设置中搜索 MCP，找到 MCP Servers 配置入口
添加配置：
```json
{
"mcpServers": {
"csmar": {
"command": "node",
"args": ["C:\\path\\to\\Csmar-MCP-server\\src\\index.js"],
"env": {
"CSMAR_API_BASE": "https://api.gtarsc.com",
"CSMAR_USERNAME": "你的CSMAR用户名",
"CSMAR_PASSWORD": "你的CSMAR密码",
"CSMAR_LANG": "0"
}
}
}
}
```
⚠️ 路径需替换为你实际克隆的项目路径，例如 D:\\Projects\\Csmar-MCP-server\\src\\index.js
### 5. 重启 Claude Code
重启 Claude Code 以加载 MCP 服务器。
### 6. 配置 Codex（可选）
Codex 使用 `~/.codex/config.toml` 管理 MCP 服务，也可以通过 `codex mcp add` 命令添加。请先确认本机已经安装 CSMAR-PYTHON SDK。
PowerShell 示例：
```powershell
codex mcp add csmar `
--env PYTHON_PATH="C:\path\to\python.exe" `
--env CSMAR_USERNAME="你的CSMAR用户名" `
--env CSMAR_PASSWORD="你的CSMAR密码" `
--env CSMAR_LANG="0" `
-- node "C:\path\to\Csmar-MCP-server\src\index.js"
```
如果使用校园网/IP 认证，可以省略 `CSMAR_USERNAME` 和 `CSMAR_PASSWORD`。如果 SDK 不在默认 Python 环境里，请额外添加：
```powershell
--env CSMAR_SDK_PATH="D:\python\Lib\site-packages\csmarapi"
```
也可以手动编辑 `~/.codex/config.toml`：
```toml
[mcp_servers.csmar]
command = "node"
args = ["C:\\path\\to\\Csmar-MCP-server\\src\\index.js"]
[mcp_servers.csmar.env]
PYTHON_PATH = "C:\\path\\to\\python.exe"
CSMAR_USERNAME = "你的CSMAR用户名"
CSMAR_PASSWORD = "你的CSMAR密码"
CSMAR_LANG = "0"
```
添加后重启 Codex，或在 Codex 中使用 `/mcp` 查看 MCP 服务是否加载成功。
## 🔧 使用方法
### 验证安装
```python
mcp__csmar__csmar_health_check()
```
### 基本数据探索
```python
# 列出所有可用数据库（约240个）
mcp__csmar__csmar_list_databases()
# 查看"财务报表"数据库中的表
mcp__csmar__csmar_list_tables(database_name="财务报表")
# 查看"FS_Combas"表的字段
mcp__csmar__csmar_list_fields(table_name="FS_Combas")
# 预览表数据（前几行）
mcp__csmar__csmar_preview(table_name="FS_Combas")
```
### 数据查询示例
```python
# 查询财务报表数据
mcp__csmar__csmar_query(
table_name="FS_Combas",
columns=["Stkcd", "ShortName", "Accper", "Typrep", "A001000000"],
condition="Stkcd like '3%' and Typrep='A'",
start_time="2020-01-01",
end_time="2021-12-31",
limit=5
)
# 查询记录数量
mcp__csmar__csmar_query_count(
table_name="FS_Combas",
condition="Stkcd like '3%'",
start_time="2020-01-01",
end_time="2021-12-31"
)
# 获取股票数据
mcp__csmar__get_stock_data(
stock_code="000001",
start_date="2024-01-01",
end_date="2024-12-31",
frequency="daily"
)
# 获取财务数据
mcp__csmar__get_financial_data(
stock_code="000001",
start_date="2020-01-01",
end_date="2024-12-31",
indicators=["A001000000", "A002000000"]
)
# 获取公司信息
mcp__csmar__get_company_info(stock_code="000001")
```
## 🛠️ 可用工具
| 工具名称 | 描述 | 参数 |
|---------|------|------|
| `csmar_health_check` | 检查服务健康状态 | 无 |
| `csmar_login` | 登录 CSMAR 账户 | `account`, `pwd`, `lang` |
| `csmar_list_databases` | 列出可访问的数据库 | 无 |
| `csmar_list_tables` | 列出数据库中的表 | `database_name` |
| `csmar_list_fields` | 列出表中的字段 | `table_name` |
| `csmar_query` | 通用数据查询 | `table_name`, `columns`, `condition`, `start_time`, `end_time`, `limit`, `format` |
| `csmar_preview` | 预览表数据 | `table_name` |
| `csmar_query_count` | 查询记录数量 | `table_name`, `columns`, `condition`, `start_time`, `end_time` |
| `get_stock_data` | 获取股票交易数据 | `stock_code`, `start_date`, `end_date`, `frequency` |
| `get_financial_data` | 获取财务数据 | `stock_code`, `start_date`, `end_date`, `indicators` |
| `get_company_info` | 获取公司基本信息 | `stock_code` |
## 📁 项目结构
```
csmar-mcp-server/
├── src/
│ ├── index.js # MCP 服务器主文件
│ └── python_client.py # Python 客户端
├── config/
│ ├── .env.example # 环境变量示例
│ └── mcp.example.json # MCP 配置示例
├── docs/
│ ├── CSMAR_MCP_配置完成报告.md
│ ├── 快速开始指南.md
│ └── CSMAR机构账号配置指南.md
├── examples/
│ └── test_input.json # 测试输入示例
├── package.json # Node.js 依赖
├── README.md # 本文件
└── .gitignore # Git 忽略文件
```
## 🔍 数据库推荐
### 常用数据库
- **财务报表**：`财务报表`, `FS_Combas`, `FS_Comins`, `FS_Comscfd`
- **股票交易**：`股票市场交易数据`, `股票日行情`
- **公司信息**：`公司基本信息`, `上市公司基本信息`
- **宏观经济**：`宏观经济数据库`
### 数据时间范围
- **财务报表**：2018-2022 年
- **AI 相关数据**：2024-2025 年
- **股票交易**：实时更新
## ⚠️ 注意事项
### 查询限制
- **每次最多 20 万条记录**：大数据集需要分页查询
- **相同条件 30 分钟限流**：避免频繁查询相同条件
- **时间格式**：必须使用 "YYYY-MM-DD" 格式
### 分页查询示例
```python
# 第1页
condition = "Stkcd like '3%' limit 0,200000"
# 第2页
condition = "Stkcd like '3%' limit 200000,200000"
mcp__csmar__csmar_query(
table_name="FS_Combas",
columns=["Stkcd", "ShortName", "Accper", "Typrep"],
condition=condition
)
```
## 🐛 故障排除
### 常见问题
#### 1. "MCP 服务器未响应"
- 确认 Claude Code 已重启
- 检查配置文件路径是否正确
- 手动测试 Python 客户端：
```bash
echo '{"action":"check_availability","params":{}}' | python src/python_client.py --once
```
#### 2. "数据库不存在"
- 使用 `csmar_list_databases()` 获取准确名称
- 检查数据库名称是否包含空格
- 确认账号有该数据库访问权限
#### 3. 查询结果为空
- 检查时间范围是否正确
- 验证查询条件语法
- 使用 `preview()` 先查看数据格式
#### 4. CSMAR SDK 导入失败
- 确认 CSMAR-PYTHON SDK 已正确安装
- 运行 `python src/python_client.py` 查看详细错误信息
### 日志文件
- **Python 客户端日志**：通过 stderr 输出
- **MCP 服务器日志**：通过 stderr 输出
## 🔄 更新日志
### v1.1.0 (2026-04-15)
- ✨ 新增持久化 Python 进程模式，大幅提升性能
- ✨ 新增健康检查工具 `csmar_health_check`
- ✨ 实现了 `get_stock_data`、`get_financial_data`、`get_company_info` 工具
- 🔧 修复 Python 路径硬编码问题，自动检测 site-packages
- 🔧 修复 zod 导入问题
- 🔧 添加请求重试机制
- 🔧 添加优雅关闭支持
### v1.0.0
- 🎉 初始版本
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request
## 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
## 🙏 致谢
- **CSMAR（国泰安）**：提供金融数据服务
- **Anthropic**：开发 Model Context Protocol
- **Claude Code**：优秀的 AI 编程环境
- **Codex**：协助项目整理、隐私检查和开源文档完善
## 📞 支持
- **CSMAR 官方支持**：service@gtadata.com，400-888-3636
- **项目反馈**：请在你发布的 GitHub 仓库 Issues 页面提交
- **文档**：查看 `docs/` 目录下的详细指南
---
**💡 提示**：开始使用前，请确保已正确配置 CSMAR 账号和环境变量！
