CSMAR Web-API MCP

An MCP server that lets Claude (or any MCP client) search, browse, preview, and download CSMAR (国泰安) data — no account, no password, no browser, no official SDK.

Authentication is done purely through your institutional IP (e.g. a subscribing university's campus network): the CSMAR website (data.csmar.com) grants an access token to recognized IPs, and this server replicates the website's IP-token + JSON HTTP API with requests (plus one WebSocket for download-ready notifications).

⚠️ You must be on a network IP that already has CSMAR access (a campus / institutional network that subscribes to CSMAR). Auth is IP-based — there is no login form. On any other network csmar_status will report IP授权: false and nothing will work. This tool only replicates the public web endpoints you are already authorized to use; it does not bypass access control or share accounts. Follow CSMAR's Terms of Service.

English

Requirements

• A network IP with CSMAR access (subscribing institution / campus network).

• Python 3.10+ with:

  pip install mcp requests websocket-client pandas openpyxl

Install (project-scoped)

1. Copy the example config and edit paths for your machine:

   cp .mcp.json.example .mcp.json
   # edit "command" -> your python, and the server.py absolute path

2. Restart your MCP client (e.g. Claude Code) to load the csmar server.

Environment variables (in .mcp.json env):

• CSMAR_LANG: 1 = English UI (English field names; search with English terms), 0 = Chinese UI. Default 1.

• CSMAR_OUT_DIR: default directory for bulk downloads. Default ~/Downloads.

Tools (11)

Discovery

Data (table accepts a table_id or a table name)

Convenience

Dates are YYYY-MM-DD; fields defaults to all; codes defaults to all; frequency ∈ daily/weekly/monthly/annual.

All four data tools also accept conditions — a list of field filters, e.g. [{"field":"Clsprc","op":">","value":"100"}]. Operators: > >= < <= = != like not like is null not is null; multiple conditions are AND-joined by default ("relation":"or" per item to OR).

Example prompts

• "Check the CSMAR connection" → csmar_status

• "Search for stock trading tables" → csmar_search("stock")

• "What fields does the daily stock table have?" → csmar_list_fields("Daily Stock Price & Returns")

• "Preview PE/PB for the first week of July 2026" → csmar_preview(3673,"2026-07-01","2026-07-07",["TradingDate","Symbol","PE","PB"])

• "Download this range as Excel" → csmar_download(3673,"2026-07-01","2026-07-07")

• "Daily quotes for 000001 in Dec 2024" → get_stock_data("000001","2024-12-01","2024-12-31")

Limits (CSMAR side)

• Preview is capped at 200 rows (use csmar_query/csmar_download for more).

• A single query returns at most 200,000 records; the time span per query is capped by frequency (e.g. daily ≤ 2 years). Narrow the range if it errors.

• Identical queries may be rate-limited briefly; transient slowness/timeouts are retried automatically.

• Only single-table queries (Data Query) are covered; cross-table query is not implemented.

Deliberate non-goals

• Resolving a table by its physical name (e.g. TRD_Dalyr) cold: CSMAR's search index does not contain physical names and there is no name→id endpoint, so pass a table_id (from csmar_search/csmar_list_tables) or a table display name. A physical name works only after that table has been accessed once in the session.

• A get_financial_data convenience tool: financial figures span many tables with consolidation / parent-only / report-type nuances that a naive indicators=[…] wrapper would silently get wrong. Use csmar_search → csmar_query (with fields/conditions) instead, which is explicit and correct.

How it works

• Auth: POST /api/csmar-main/automaticLogin (self-generated signCode UUID + IP) → token.

• Search: POST /api/csmar-main/highlight/searchData.

• Catalog: GET /api/csmar-main/single/getSeriesTree/-1; tables: GET .../getSingleTableLeftTree/{dbId}.

• Fields: GET /api/csmar-main/single/getSampleData/{tableId}.

• Preview: POST .../csmar-single/single/cacheCondition → GET .../preview/{id} (selected fields need isChecked=1).

• Download: saveOutline → singleData/pack (async) → WebSocket wss://data.csmar.com/ws send {outlineId,status:"start",token,signCode}, receive {filePath} → fetch zip from https://file.csmar.com/{filePath} (contains the .xlsx). CSMAR xlsx has 3 header rows (name / description / unit).

Related MCP server: FinData MCP Server

中文

前提

• 本机处于已订阅 CSMAR 的机构 IP（校园网）环境。鉴权靠 IP，无登录表单；换到没授权的网络，csmar_status 会显示 IP授权: false，所有功能不可用。

• Python 3.10+：

  pip install mcp requests websocket-client pandas openpyxl

安装（项目级）

1. 复制示例配置并按本机改路径：

   cp .mcp.json.example .mcp.json
   # 改 "command" 为你的 python，args 改成 server.py 的绝对路径

2. 重启 MCP 客户端（如 Claude Code）即加载 csmar 服务。

环境变量（.mcp.json 的 env）：

• CSMAR_LANG：1=英文界面（字段名英文、搜索用英文词），0=中文界面。默认 1。

• CSMAR_OUT_DIR：批量下载默认目录。默认 ~/Downloads。

工具（11 个）

探索类

取数类（table 可传 table_id 或表名）

便捷封装

日期格式 YYYY-MM-DD；fields 缺省=全部；codes 缺省=全部；frequency ∈ daily/weekly/monthly/annual。

四个取数工具都支持 conditions（字段筛选），例：[{"field":"Clsprc","op":">","value":"100"}]。 运算符：> >= < <= = != like not like is null not is null；多条件默认 AND（单条加 "relation":"or" 可 OR）。

典型用法（对 Claude 说）

• “确认 CSMAR 能连吗” → csmar_status

• “搜股票交易相关的表” → csmar_search("stock")

• “日行情表有哪些字段” → csmar_list_fields("Daily Stock Price & Returns")

• “预览 2026-07 第一周的 PE、PB” → csmar_preview(3673,"2026-07-01","2026-07-07",["TradingDate","Symbol","PE","PB"])

• “这段完整下载成 Excel” → csmar_download(3673,"2026-07-01","2026-07-07")

• “000001 在 2024-12 的日行情” → get_stock_data("000001","2024-12-01","2024-12-31")

限制（CSMAR 侧）

• 预览每次最多 200 行（更多用 csmar_query/csmar_download）。

• 单次查询最多 20 万条；时间跨度上限因频率而异（如日频 ≤ 2 年）。超限就缩小范围。

• 相同查询短时间内可能被限流；偶发慢/超时已内置重试。

• 仅覆盖单表查询（Data Query）；跨表查询未实现。

有意不做的两点

• 冷启动用物理表名（如 TRD_Dalyr）解析表：CSMAR 搜索索引不含物理名，也没有「按名查 id」的端点，所以请传 table_id（来自 csmar_search/csmar_list_tables）或表显示名；物理名仅在该表本会话内被访问过后才可用。

• get_financial_data 便捷工具：财务数据跨多张表，且有合并/母公司、报表类型等口径差异，indicators=[…] 式的封装很容易给出「看似对实则错」的数字。改用 csmar_search → csmar_query（配 fields/conditions）更明确也更可靠。

实现说明

参见上方 English → How it works。核心：IP 换 token → 搜索/浏览/预览（HTTP JSON）→ 下载走 saveOutline+pack（异步）+ WebSocket 拿文件路径 → 从 file.csmar.com 取 zip（内含 xlsx，前 3 行为 字段名/描述/单位）。

Disclaimer

This project replicates the public web endpoints that your own institutional IP is already authorized to access. It does not bypass access control, crack authentication, or share accounts. Use it in accordance with CSMAR's Terms of Service and your institution's license.