CSMAR-MCP-server

CSMAR MCP Server [](LICENSE) [](https://spec.modelcontextprotocol.io) [](https://nodejs.org) [](https://www.python.org) The Model Context Protocol (MCP) server for CSMAR financial database, supporting direct access to CSMAR financial data in MCP clients like Codex, Claude Code, etc. Publisher: Xiaohongshu Blogger: Life on the Road For detailed installation, configuration, and open-source notes, see [使用说明.md](使用说明.md). ## ✨ Features - **Complete CSMAR Data Access**: Supports 240+ databases, including financial statements, stock trading, company information, etc. - **Intelligent Login Management**: Supports automatic login with environment variables and token caching. - **13 MCP Tools**: Covers database exploration, directory search, data query, preview, and export. - **Persistent Python Processes**: Reuses Python sessions, significantly improving performance. - **Request Retry Mechanism**: Automatically retries network is unstable. - **Graceful Shutdown**: Supports SIGTERM/SIGINT signals. - **Health Check**: View service status at any time. - **Python Middleware**: Stable encapsulation based on CSMAR-PYTHON SDK. - **Simple Configuration**: Supports integration with Codex, Claude Code, and other MCP clients. ## 📋 Prerequisites 1. **CSMAR Account**: A valid CSMAR (Guotai An) institutional account (both personal and institutional accounts are acceptable). 2. **Python 3.8+**: Needs to install CSMAR-PYTHON SDK and its dependencies. - Install Python dependencies: `pip install urllib3 websocket websocket_client pandas prettytable`. - Download and install CSMAR-PYTHON SDK (from the official website or contact CSMAR). 3. **Node.js 18+**: Run the MCP server. 4. **MCP Client**: Codex, Claude Code, or other MCP-supported clients. ## 🚀 Quick Start ### 1. Clone the Project ```bash git clone <YOUR_GITHUB_REPO_URL> cdar-MCP-server ``` ### 2. Install Dependencies ```bash # Install Node.js dependencies npm install # Install Python dependencies (required for CSMAR SDK) pip install urllib3 websocket websocket_client pandas prettytable # Install CSMAR-PYTHON SDK # Download the SDK package from the CSMAR website, extract it to the Python site-packages directory # or follow the official documentation: https://www.gtadata.com/products/csmar-api ``` ### 3. Configure Environment Variables Create a `.env` file in the project root directory: ```env # CSMAR configuration CSMAR_API_BASE=https://api.gtarsc.com CSMAR_USERNAME=your CSMAR username CSMAR_PASSWORD=your CSMAR password CSMAR_LANG=0 # 0=Chinese, 1=English ``` > ⚠️ **Security Tip**: Do not submit the `.env` file to Git! `.gitignore` is configured to automatically ignore it. ### 4. Configure Claude Code (including Claude client and VS Code extension configuration methods) In Claude Code's configuration file, add the MCP server configuration: **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.gtarsc.com "CSMAR_USERNAME": "your CSMAR username", CSMAR_PASSWORD": "your CSMAR password", "CSMAR_LANG": "0 } } **macOS/Linux** (`config/Claude_desktop_config.json```json { mcpServers": { mar": { ": "node", args": ["/pathsmar-MCP-server"], " { "CSMAR": "https://apic.com", MAR_USERNAME": "your username", "CSMAR_PASSWORD": "your CSM", "CSMAR_LANG": "0" } } } } ``` the Claude Code extension in, configure as follows the env file, the Claude Code MCP configuration The MCP configuration file for Claude VS Code is located```code %AP%/Code/User/globalaoudval.claudecp.json ``` for MCP in the VS and find the MCP Servers Add the configuration: ```{ "m": { mar": { " "node", ": ["C:\\path\\Csmar-server\\src\\index "env": { "CSMAR_API_BASEhttps://api.gt.com", "CS": "your CSMAR "CSMAR "your CSMAR password "CSMAR_LANG0" } } } } ``` the path with your actual, e.g.,Projects\\CsmCP-server\\index.js`. ### Restart Claude Code to load the. ### 6.x (optional) Codex uses `~/.codex/config.toml` to manage MCP services, or you can add it using the `codex mcp add` command. Make sure the CSMAR-PYTHON SDK is installed on your machine. PowerShell example: ```powershell codex csmar ` --env PYTHON_PATH="C:\pathpython.exe" ` --env CSMAR_USERNAME="your CSMAR username" ` --env CSMAR_PASSWORD="your CSMAR password" ` --env CSMAR_LANG="0" ` -- node "C:\path\to\Csm-server\src\index.js" ``` If using campus network/IP authentication, you can omit `CSMAR_USERNAME` and `CSMAR_PASSWORD`. If the SDK is not in the default add: ```powershell --env CSMAR_SDK_PATH="D:\python\Lib\site-packages\csmarapi" ``` You can also~/.codex/config.toml`: ```toml [mcp_servers.csmar] command = "node" args = ["C:\\pathCsmar-MCP-server\\src\\index.js"] [mcp_servers.csmar.env] PYTHON_PATH = "C:\\path\\to\\python.exe" CSMAR_USERNAME = "your CSMAR username" CSMAR_PASSWORD = " password" CS = "0" x after adding,mcp`x to check if the loaded successfully. Usage ### ```python mmar__cs() ``` ### Basic Data Exploration # List all available databases (aboutmcp____csmar_list# View tables in the "Financial Statements" databasecp__csmar__csmar_list_tables(database Statements") # View fields in the "FS_Com mcp__csmar__csmar_list_fields(table_name="FS_Com Preview table data (first few rows) mcp__csmar__csmar_preview(table_name="FS_Combas") ``` ### Data Query```python # Query financial statement data mcp__csmar_query( table_name="FS", columns=["Stkcd", "Short "Accper", "Typrep", "A001000000"], condition="Stkcd like '3%' and Typrep='A'", start_time="2020-01-01", end_time="2021-12-31", limit=5 ) # Query record count mcp__csmar_query_count( table_namebas", condition="Stkcd like '3%'", start_time="202001", end_time="2021-12" ) # Get stock data mcp__csmar__get_stock_data( stock_code="000001", start_date="2024-01-01", ="2024-12-31", frequency) # Get financial data mcp__csmar__get_financial_data( stock_code="000001", start_date="2020-01-01 end_date="2024-12-31", A001000000", "A002000000"] ) # Get company information mcp__csmar__get_company_info(stock_code="000001") ``` ## | Tool Name | Description | Parameters | ------| | `csmar_health_check` | Check service health | None | | `csmar_login` | Login CSMAR account | `account`, `pwd`, ` | | `csmar_list_databases` | | None | | `csmar_list_tables` | List tables in a database | `database_name` | | `csmar_list_fields` | List fields in a table_name` | | `csmar_query` | General data query | `table_name`, `columns`,start_time`, `end_time`, `limit`, `format` | | `csmar_preview` | Preview table data | `table_name` | | `csmar` | Query record count | `table_name`, `columns`, `condition`, `start_time`, `end_time` | | `get | Get stock trading data | `stock_code`, `start_date`, `end `frequency` | | `get_financial_data` | Get financial data | `stock_code`, `startend_date`, `indicators` | | `get_company_info` | Get basic company information | `stock_code` | ## 📁 Project Structure ``` csmar-mcp-server/ ├── src/ │ ├── index.js # MCP server main file │ └── python_client.py # Python client ├── config/ │ ├── .env.example # Environment variable example │ └── mcp.example.json # MCP configuration example ├── docs/ │ CSMAR_MCP_Configuration_Report.md Quick_Start_Guide.md │ └──_Institutional_Account_Configuration_Guide.md/ │ └── test_input.json # Test input example ├── package.json # Node.js dependencies ├── README.md # This file └── .gitignore # Git ignore file ``` ## 🔍 Recommended Databases ### Common Databases - **Financial Statements**: `Financial Statements`, `FS_Combas`, `FS_Comins`, `FS_Comscfd` - **Stock Trading**: `Stock Market Trading Data`, `Stock Daily Quotes` - **Company Information**: `Basic Company Information`, `Listed Company Basic Information` - **Macroeconomics**: `Macroeconomic Database` ### Data Time Range - **Financial Statements**: 2018-2022 - **AI-related Data**: 2024-2025 - **Stock Trading**: Real-time updates ⚠️ Notes ### Query Limitations -200,000 records per query**: Large datasets queries. - **30-minute rate limit for same conditions**: Avoid frequent queries with the same conditions. - **Time format**: Must use "YYYY-MM-DD" formataginated Query Examplepython # Page condition = "cd like '3%' limit 0,200000" # Page 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: ```bash echo '{"action":"check_avparams":{}}' | python src/python_client.py --once ``` #### 2. "Database Does Not Exist" - Use `csmar_list_databases()` to get the accurate name. - Check if the database name contains spaces. - Confirm the account has access to the database. #### 3. Empty Query Results - Check if the time range is correct. - Verify the query condition syntax. - Use `preview()` to view the data format. #### 4. CSMAR SDK Import Failure - Confirm the CSMAR-PYTHON SDK is correctly installed. - Run `python src/python_client.py` to view. ### Log Files - **Python Client through stderr. - **MCP Server Logs**: Output through stderr. ## 🔄 Update Log ### v1.1.0 (2026-04-15) - ✨ Added persistent Python process mode, significantly improving performance. - ✨ Added health check tool `csmar_health_check`. - ✨ Implemented `get_stock_data`, `get_financial_data`, `get_company_info` tools. - 🔧 Fixed Python path hardcoding issue, automatically detecting site-packages. - 🔧 Fixed zod import issue. - 🔧 Added request retry mechanism. - 🔧 Added graceful shutdown support. ### v1.0.0 - 🎉 Initial version. ## 🤝 Contribution Welcome to submit issues and pull requests! 1. Fork the project. 2. Create a feature branch (`git checkout -b feature/amazing-feature`). 3. Commit 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 uses the MIT license - see [) for details. ## 🙏 Acknowledgments **CSMAR (Guotai An)**: Provides financial data services. - **Anthropic**: Developed the Model Context Protocol. - **Claude Code**: Excellent AI programming environment. - **Codex**: Assisted in project organization, privacy checks, and open-source documentation improvement. ## 📞 Support CSMAR Official Support**: service@gtadata.com, 400-888-- **Project Feedback**: Please submit issues on your GitHub repository's Issues page. - **Documentation**: guides in the `docs/` directory. --- **💡 Tip**: Before using, ensure that the CSMAR account and environment variables are correctly configured!