Servidor MCP de CSMAR

License MCP Protocol

Servidor del Protocolo de Contexto de Modelo (MCP) para la base de datos financiera Guotai'an (CSMAR), que permite el acceso directo a los datos financieros de CSMAR en Claude Code.

✨ Características

Acceso completo a los datos de CSMAR: Admite más de 240 bases de datos, incluidos estados financieros, negociación de acciones, información de empresas, etc.
Gestión inteligente de inicio de sesión: Admite inicio de sesión automático mediante variables de entorno y almacenamiento en caché de tokens.
11 herramientas MCP: Cubre funciones completas como exploración de bases de datos, consulta de datos y vista previa.
Capa intermedia de Python: Encapsulación estable basada en el SDK de CSMAR-PYTHON.
Configuración sencilla: Configuración con un solo clic, compatible con la integración nativa de Claude Code.

📋 Requisitos previos

Cuenta de CSMAR: Cuenta institucional válida de CSMAR (Guotai'an).
Python 3.8+: Se requiere la instalación del SDK de CSMAR-PYTHON.
Node.js 18+: Para ejecutar el servidor MCP.
Claude Code: La versión más reciente del editor Claude Code.

🚀 Inicio rápido

1. Clonar el proyecto

git clone https://github.com/yourusername/csmar-mcp-server.git
cd csmar-mcp-server

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Copie la plantilla del archivo de configuración:

cp config/.env.example .env

Edite el archivo .env e introduzca la información de su cuenta de CSMAR:

CSMAR_API_BASE=https://api.gtarsc.com
CSMAR_API_KEY=你的API密钥（如有）
CSMAR_USERNAME=你的CSMAR用户名
CSMAR_PASSWORD=你的CSMAR密码
CSMAR_LANG=0  # 0=中文, 1=英文

4. Configurar Claude Code

Añada la configuración del servidor MCP en el archivo de configuración de Claude Code:

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

5. Reiniciar Claude Code

Reinicie Claude Code para cargar el servidor MCP.

🔧 Modo de uso

Verificar la instalación

Ejecute en Claude Code:

mcp__csmar__csmar_list_databases()

Si ve la lista de bases de datos, ¡la instalación se realizó correctamente!

Exploración básica de datos

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

Ejemplo de consulta de datos

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

🛠️ Herramientas disponibles

Nombre de la herramienta	Descripción	Parámetros
`csmar_login`	Iniciar sesión en la cuenta de CSMAR	`account`, `pwd`, `lang`
`csmar_list_databases`	Listar bases de datos accesibles	Ninguno
`csmar_list_tables`	Listar tablas en la base de datos	`database_name`
`csmar_list_fields`	Listar campos en la tabla	`table_name`
`csmar_query`	Consulta de datos general	`table_name`, `columns`, `condition`, `start_time`, `end_time`, `limit`, `format`
`csmar_preview`	Vista previa de datos de la tabla	`table_name`
`csmar_query_count`	Consultar número de registros	`table_name`, `columns`, `condition`, `start_time`, `end_time`
`get_stock_data`	Obtener datos de negociación de acciones	`stock_code`, `start_date`, `end_date`, `frequency`
`get_financial_data`	Obtener datos financieros	`stock_code`, `start_date`, `end_date`, `indicators`
`get_company_info`	Obtener información básica de la empresa	`stock_code`

📁 Estructura del proyecto

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 忽略文件

🔍 Recomendaciones de bases de datos

Bases de datos comunes

Estados financieros: 财务报表, FS_Combas, FS_Comins, FS_Comscfd
Negociación de acciones: 股票市场交易数据, 股票日行情
Información de empresas: 公司基本信息, 上市公司基本信息
Macroeconomía: 宏观经济数据库

Rango de tiempo de los datos

Estados financieros: 2018-2022
Datos relacionados con IA: 2024-2025
Negociación de acciones: Actualización en tiempo real

⚠️ Notas importantes

Limitaciones de consulta

Máximo 200,000 registros por vez: Los conjuntos de datos grandes requieren consultas paginadas.
Límite de tasa de 30 minutos para la misma condición: Evite consultas frecuentes con las mismas condiciones.
Formato de tiempo: Debe utilizar el formato "YYYY-MM-DD".

Ejemplo de consulta paginada

# 第1页
条件 = "Stkcd like '3%' limit 0,200000"
# 第2页
条件 = "Stkcd like '3%' limit 200000,200000"

mcp__csmar__csmar_query(
    table_name="FS_Combas",
    columns=["Stkcd", "ShortName", "Accper", "Typrep"],
    condition=条件
)

🐛 Solución de problemas

Preguntas frecuentes

1. "El servidor MCP no responde"

Confirme que Claude Code se haya reiniciado.
Verifique la ruta del archivo .mcp.json.

Pruebe manualmente el cliente de Python:

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

2. "La base de datos no existe"

Utilice csmar_list_databases() para obtener el nombre exacto.
Compruebe si el nombre de la base de datos contiene espacios.
Confirme que la cuenta tiene permisos de acceso a esa base de datos.

3. Los resultados de la consulta están vacíos

Compruebe si el rango de tiempo es correcto.
Verifique la sintaxis de la condición de consulta.
Utilice preview() primero para ver el formato de los datos.

4. Error al importar el SDK de CSMAR

Confirme que el SDK de CSMAR-PYTHON esté instalado correctamente.
Compruebe la configuración de la ruta de Python.
Revise la configuración de la ruta en src/python_client.py.

Archivos de registro

Registros de CSMAR: csmar-log.log
Registros del cliente de Python: Salida a través de stderr.
Registros del servidor MCP: Salida a través de stderr.

🤝 Contribución

¡Las propuestas de Issues y Pull Requests son bienvenidas!

Haga un Fork del proyecto.
Cree una rama de funciones (git checkout -b feature/amazing-feature).
Confirme sus cambios (git commit -m 'Add amazing feature').
Envíe a la rama (git push origin feature/amazing-feature).
Cree un Pull Request.

📄 Licencia

Este proyecto está bajo la licencia MIT - consulte el archivo LICENSE para obtener más detalles.

🙏 Agradecimientos

CSMAR (Guotai'an): Por proporcionar servicios de datos financieros.
Anthropic: Por desarrollar el Protocolo de Contexto de Modelo (MCP).
Claude Code: Por el excelente entorno de programación con IA.

📞 Soporte

Soporte oficial de CSMAR: service@gtadata.com, 400-888-3636
Issues del proyecto: GitHub Issues
Documentación: Consulte la guía detallada en el directorio docs/.

💡 Consejo: ¡Antes de empezar, asegúrese de haber configurado correctamente su cuenta de CSMAR y las variables de entorno!

CSMAR MCP Server