CSMAR MCP Server

A Model Context Protocol (MCP) server for the CSMAR financial database, enabling direct access to CSMAR financial data within Claude Code.

✨ Features

• Full CSMAR Data Access: Supports 240+ databases, including financial statements, stock trading data, company information, and more.

• Intelligent Login Management: Supports automatic login via environment variables and token caching.

• 11 MCP Tools: Comprehensive functionality covering database exploration, data querying, previewing, and more.

• Persistent Python Process: Reuses Python sessions to significantly improve performance.

• Request Retry Mechanism: Automatically retries when network instability occurs.

• Graceful Shutdown: Supports SIGTERM/SIGINT signals.

• Health Checks: Monitor service status at any time.

• Python Middleware: Stable encapsulation based on the CSMAR-PYTHON SDK.

• Simple Configuration: One-click configuration with native Claude Code integration.

Related MCP server: cn-financial-mcp

📋 Prerequisites

1. CSMAR Account: A valid CSMAR (GTA) institutional account (personal or institutional accounts are both supported).

2. Python 3.8+: Requires the CSMAR-PYTHON SDK and its dependencies.

   • Install Python dependencies: pip install urllib3 websocket websocket_client pandas prettytable

   • Download and install the CSMAR-PYTHON SDK (from the official website or by contacting CSMAR).

3. Node.js 18+: To run the MCP server.

4. Claude Code: The latest version of the Claude Code editor.

🚀 Quick Start

1. Clone the Project

git clone https://github.com/ww11-max/Csmar-MCP-server.git
cd Csmar-MCP-server

2. Install Dependencies

# 安装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. Configure Environment Variables

Create a .env file in the project root directory:

# CSMAR 配置
CSMAR_API_BASE=https://api.gtarsc.com
CSMAR_USERNAME=你的CSMAR用户名
CSMAR_PASSWORD=你的CSMAR密码
CSMAR_LANG=0  # 0=中文, 1=英文

⚠️ Security Tip: Do not commit the .env file to Git! It is already configured in .gitignore to be ignored automatically.

4. Configure Claude Code (Includes both Claude Desktop and VS Code extension configuration methods)

Add the MCP server configuration to your Claude Code configuration file:

Windows (%APPDATA%/Claude/claude_desktop_config.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):

{
  "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"
      }
    }
  }
}

If you are using the Claude Code extension in VS Code, configure it as follows:

After configuring the env file, modify the Claude Code MCP configuration. The MCP configuration file for Claude Code in VS Code is located at:

%APPDATA%/Code/User/globalStorage/saoudval.claude-code/mcp.json

Alternatively, search for "MCP" in VS Code settings to find the MCP Servers configuration entry. Add the configuration:

{
  "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"
      }
    }
  }
}

⚠️ The path must be replaced with your actual cloned project path, e.g., D:\Projects\Csmar-MCP-server\src\index.js

5. Restart Claude Code

Restart Claude Code to load the MCP server.

🔧 Usage

Verify Installation

mcp__csmar__csmar_health_check()

Basic Data Exploration

# 列出所有可用数据库（约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")

Data Query Example

# 查询财务报表数据
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")

🛠️ Available Tools

📁 Project Structure

csmar-mcp-server/
├── src/
│   ├── index.js              # MCP 服务器主文件
│   └── python_client.py      # Python 客户端
├── config/
│   ├── .env.example          # 环境变量示例
│   └── .mcp.json             # MCP 配置示例
├── docs/
│   ├── CSMAR_MCP_配置完成报告.md
│   ├── 快速开始指南.md
│   └── CSMAR机构账号配置指南.md
├── examples/
│   └── test_input.json       # 测试输入示例
├── package.json              # Node.js 依赖
├── README.md                 # 本文件
└── .gitignore               # Git 忽略文件

🔍 Recommended Databases

Common Databases

• Financial Statements: 财务报表, FS_Combas, FS_Comins, FS_Comscfd

• Stock Trading: 股票市场交易数据, 股票日行情

• Company Info: 公司基本信息, 上市公司基本信息

• Macroeconomics: 宏观经济数据库

Data Time Range

• Financial Statements: 2018-2022

• AI-related Data: 2024-2025

• Stock Trading: Updated in real-time

⚠️ Notes

Query Limits

• Max 200,000 records per query: Large datasets require paginated queries.

• 30-minute rate limit for identical conditions: Avoid frequent queries with the same conditions.

• Time Format: Must use "YYYY-MM-DD" format.

Paginated Query Example

# 第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
)

🐛 Troubleshooting

Common Issues

1. "MCP Server not responding"

• Confirm Claude Code has been restarted.

• Check if the configuration file path is correct.

• Manually test the Python client:

  echo '{"action":"check_availability","params":{}}' | python src/python_client.py --once

2. "Database does not exist"

• Use csmar_list_databases() to get the exact name.

• Check if the database name contains spaces.

• Confirm your account has access to that database.

3. Query results are empty

• Check if the time range is correct.

• Verify the query condition syntax.

• Use preview() to check the data format first.

4. CSMAR SDK import failure

• Confirm the CSMAR-PYTHON SDK is installed correctly.

• Run python src/python_client.py to view detailed error information.

Log Files

• Python Client Logs: Output via stderr.

• MCP Server Logs: Output via stderr.

🔄 Changelog

v1.1.0 (2026-04-15)

• ✨ Added persistent Python process mode for significantly improved performance.

• ✨ Added csmar_health_check tool.

• ✨ Implemented get_stock_data, get_financial_data, and get_company_info tools.

• 🔧 Fixed hardcoded Python path issue; now automatically detects site-packages.

• 🔧 Fixed zod import issue.

• 🔧 Added request retry mechanism.

• 🔧 Added graceful shutdown support.

v1.0.0

• 🎉 Initial release.

🤝 Contributing

Issues and Pull Requests are welcome!

1. Fork the project.

2. Create a feature branch (git checkout -b feature/amazing-feature).

3. Commit your changes (git commit -m 'Add amazing feature').

4. Push to the branch (git push origin feature/amazing-feature).

5. Create a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• CSMAR (GTA): For providing financial data services.

• Anthropic: For developing the Model Context Protocol.

• Claude Code: For the excellent AI programming environment.

📞 Support

• CSMAR Official Support: service@gtadata.com, 400-888-3636

• Project Issues: GitHub Issues

• Documentation: See the detailed guides in the docs/ directory.

💡 Tip: Before you start, ensure your CSMAR account and environment variables are configured correctly!