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

Tool	Purpose	Key args
csmar_status	Check login / institution / IP-access status	—
csmar_list_databases	List the database catalog (with subscription flag)	only_accessible, keyword
csmar_list_tables	List tables under a database	database_id
csmar_search	Keyword search over tables/fields → get table_id	keyword, page_size
csmar_list_fields	List a table's fields, time/code field, samples	table (id or name)

Data (table accepts a table_id or a table name)

Tool	Purpose	Key args
csmar_query_count	Count matching records	table, start_date, end_date, codes?
csmar_preview	Preview rows as JSON (≤200 rows)	table, start_date, end_date, fields?, codes?
csmar_query	General query → JSON; limit>200 auto-uses background packaging + download	table, start_date, end_date, fields?, codes?, limit
csmar_download	Download full data to local xlsx/csv	table, start_date, end_date, fields?, codes?, out_dir?, as_csv?

Convenience

Tool	Purpose	Key args
get_stock_data	Stock quotes by code (daily/weekly/monthly/annual, TRD_Dalyr etc.)	stock_code, start_date, end_date, frequency, limit
get_company_info	Company profile by code (TRD_Co)	stock_code

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).

---

中文

前提

• 本机处于已订阅 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 个）

探索类

工具	说明	关键参数
csmar_status	检查登录/机构/IP 授权状态	无
csmar_list_databases	列出数据库目录（含是否已订阅）	only_accessible, keyword
csmar_list_tables	列出某数据库下的表	database_id
csmar_search	关键词搜索库/表/字段，拿到 table_id	keyword, page_size
csmar_list_fields	列出某表的字段、时间/代码字段、样本	table（table_id 或表名）

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

工具	说明	关键参数
csmar_query_count	统计满足条件的记录总数	table, start_date, end_date, codes?
csmar_preview	取数预览，直接返回 JSON（≤200行）	table, start_date, end_date, fields?, codes?
csmar_query	通用取数返回 JSON；limit>200 自动走后台打包下载再读取	table, start_date, end_date, fields?, codes?, limit
csmar_download	批量下载完整数据，存本地 xlsx/csv	table, start_date, end_date, fields?, codes?, out_dir?, as_csv?

便捷封装

工具	说明	关键参数
get_stock_data	按股票代码取日/周/月/年行情（TRD_Dalyr 等）	stock_code, start_date, end_date, frequency, limit
get_company_info	按股票代码取公司基本信息（TRD_Co）	stock_code

日期格式 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.