tushare-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 erwanjun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# tushare-mcp-server
+
+[中文文档](README_CN.md) | English
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Tushare Pro](https://tushare.pro) financial data API. Provides AI assistants (GitHub Copilot, Claude, etc.) with direct access to comprehensive Chinese financial market data — covering A-shares, indices, funds, futures, options, bonds, forex, HK/US stocks, and macroeconomic indicators.
+
+## Features
+
+- **Universal Query** — `tushare_query` calls any of the 173 Tushare Pro APIs
+- **15 Convenience Tools** — Pre-built tools for stocks, indices, financials, funds, and more
+- **Built-in Documentation** — `get_api_doc` / `search_api_docs` for API parameter lookup
+- **Categorized Index** — 173 APIs organized into 18 categories
+
+### Data Coverage
+
+| Category | # | Examples |
+|----------|---|----------|
+| A-Shares | 37 | stock_basic, daily, weekly, monthly, daily_basic, adj_factor, pro_bar |
+| Financials | 9 | income, balancesheet, cashflow, fina_indicator, forecast |
+| Market Reference | 23 | margin, top_list, block_trade, hsgt_top10, pledge_stat |
+| Indices | 13 | index_basic, index_daily, index_weight, sw_daily, ci_daily |
+| Money Flow | 8 | moneyflow, moneyflow_hsgt, moneyflow_ind_ths |
+| Funds | 14 | fund_basic, fund_nav, fund_daily, etf_basic, fund_portfolio |
+| Futures | 8 | fut_basic, fut_daily, fut_holding, fut_mapping |
+| Options | 3 | opt_basic, opt_daily, opt_mins |
+| Bonds / CB | 9 | cb_basic, cb_daily, cb_issue, repo_daily, yc_cb |
+| HK Stocks | 9 | hk_basic, hk_daily, hk_income, hk_balancesheet |
+| US Stocks | 8 | us_basic, us_daily, us_income, us_balancesheet |
+| Macro Economy | 14 | shibor, cn_gdp, cn_cpi, cn_ppi, cn_pmi, libor |
+| Sector / Concept | 5 | ths_index, ths_daily, dc_index, dc_member |
+| Others | 13 | fx_daily, sge_daily, news, trade_cal, etc. |
+
+## Prerequisites
+
+- Python 3.10+
+- A [Tushare Pro](https://tushare.pro/register?invited_code=ANNJLJ) account and API token
+
+## Quick Start
+
+### Install via npx (recommended)
+
+No installation needed — just configure your MCP client:
+
+```json
+{
+  "servers": {
+    "tushare": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "tushare-mcp-server"],
+      "env": { "TUSHARE_TOKEN": "your_token_here" }
+    }
+  }
+}
+```
+
+### Install from source
+
+```bash
+git clone https://github.com/erwanjun/tushare-mcp-server.git
+cd tushare-mcp-server
+python3 -m venv .venv
+source .venv/bin/activate
+pip install mcp httpx
+```
+
+## Configuration
+
+### Tushare Token
+
+Set your token via any of these methods:
+
+1. **`.env` file** (recommended) — create `.env` in the project root:
+   ```
+   TUSHARE_TOKEN=your_token_here
+   ```
+2. **Environment variable** — `export TUSHARE_TOKEN=your_token`
+3. **MCP client config** — pass via the `env` field (see examples below)
+
+### VS Code (GitHub Copilot)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "tushare": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "tushare-mcp-server"],
+      "env": { "TUSHARE_TOKEN": "your_token_here" }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tushare": {
+      "command": "npx",
+      "args": ["-y", "tushare-mcp-server"],
+      "env": { "TUSHARE_TOKEN": "your_token_here" }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `tushare_query` | Universal query — call any Tushare Pro API |
+| `get_stock_list` | A-share stock list |
+| `get_trade_calendar` | Trading calendar |
+| `get_daily_bars` | Daily OHLCV (unadjusted) |
+| `get_daily_basic` | Daily indicators: PE, PB, market cap, turnover |
+| `get_income` | Income statement |
+| `get_balancesheet` | Balance sheet |
+| `get_cashflow` | Cash flow statement |
+| `get_fina_indicator` | Financial indicators (ROE, ROA, margins) |
+| `get_index_daily` | Index daily bars |
+| `get_moneyflow` | Stock money flow |
+| `get_concept` | Concept / sector classification |
+| `get_concept_detail` | Concept constituents |
+| `get_fund_basic` | Fund list |
+| `get_fund_nav` | Fund NAV |
+| `get_shibor` | Shibor interest rates |
+| `get_api_doc` | Full API documentation by endpoint name |
+| `search_api_docs` | Search API docs by keyword |
+
+## Development
+
+```bash
+# Re-crawl Tushare documentation
+python crawl_docs.py
+
+# Rebuild API index
+python build_index.py
+```
+
+## License
+
+MIT

package/README_CN.md

@@ -0,0 +1,146 @@
+# tushare-mcp-server
+
+[English](README.md) | 中文
+
+[Tushare Pro](https://tushare.pro) 金融数据 MCP 服务器。通过 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 为 AI 助手（GitHub Copilot、Claude 等）提供 A 股、指数、基金、期货、期权、债券、外汇、港股、美股、宏观经济等全方位金融数据查询能力。
+
+## 功能
+
+- **通用查询** `tushare_query` — 可调用任意 Tushare Pro 的 173 个 API 接口
+- **15 个便捷工具** — 股票列表、日线行情、每日指标、利润表、资产负债表、现金流量表、财务指标、指数日线、资金流向、概念/板块、基金列表/净值、Shibor 利率
+- **内置文档查询** `get_api_doc` / `search_api_docs` — 按接口名或关键词查询 API 参数说明
+- **分类索引** — 173 个接口按 18 个类别整理
+
+### 数据覆盖
+
+| 类别 | 数量 | 包含接口 |
+|------|------|----------|
+| 沪深股票 | 37 | stock_basic, daily, weekly, monthly, daily_basic, adj_factor, pro_bar 等 |
+| 财务数据 | 9 | income, balancesheet, cashflow, fina_indicator, forecast 等 |
+| 市场参考 | 23 | margin, top_list, block_trade, hsgt_top10, pledge_stat 等 |
+| 指数数据 | 13 | index_basic, index_daily, index_weight, sw_daily, ci_daily 等 |
+| 资金流向 | 8 | moneyflow, moneyflow_hsgt, moneyflow_ind_ths 等 |
+| 基金数据 | 14 | fund_basic, fund_nav, fund_daily, etf_basic, fund_portfolio 等 |
+| 期货数据 | 8 | fut_basic, fut_daily, fut_holding, fut_mapping 等 |
+| 期权数据 | 3 | opt_basic, opt_daily, opt_mins |
+| 债券/可转债 | 9 | cb_basic, cb_daily, cb_issue, repo_daily, yc_cb 等 |
+| 港股数据 | 9 | hk_basic, hk_daily, hk_income, hk_balancesheet 等 |
+| 美股数据 | 8 | us_basic, us_daily, us_income, us_balancesheet 等 |
+| 宏观经济 | 14 | shibor, cn_gdp, cn_cpi, cn_ppi, cn_pmi, libor 等 |
+| 概念板块 | 5 | ths_index, ths_daily, dc_index, dc_member, ths_member |
+| 其他 | 13 | fx_daily, sge_daily, news, trade_cal 等 |
+
+## 前置条件
+
+- Python 3.10+
+- [Tushare Pro](https://tushare.pro/register?invited_code=ANNJLJ) 账号及 API Token
+
+## 快速开始
+
+### 通过 npx 安装（推荐）
+
+无需手动安装，在 MCP 客户端配置即可：
+
+```json
+{
+  "servers": {
+    "tushare": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "tushare-mcp-server"],
+      "env": { "TUSHARE_TOKEN": "你的token" }
+    }
+  }
+}
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/erwanjun/tushare-mcp-server.git
+cd tushare-mcp-server
+python3 -m venv .venv
+source .venv/bin/activate
+pip install mcp httpx
+```
+
+## 配置 Token
+
+三种方式（任选一种）：
+
+1. **`.env` 文件**（推荐）：在项目根目录创建 `.env`
+   ```
+   TUSHARE_TOKEN=你的token
+   ```
+2. **环境变量**：`export TUSHARE_TOKEN=你的token`
+3. **MCP 客户端配置**：通过 `env` 字段传入（见下方示例）
+
+### VS Code (GitHub Copilot)
+
+`.vscode/mcp.json`：
+
+```json
+{
+  "servers": {
+    "tushare": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "tushare-mcp-server"],
+      "env": { "TUSHARE_TOKEN": "你的token" }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json`：
+
+```json
+{
+  "mcpServers": {
+    "tushare": {
+      "command": "npx",
+      "args": ["-y", "tushare-mcp-server"],
+      "env": { "TUSHARE_TOKEN": "你的token" }
+    }
+  }
+}
+```
+
+## 工具列表
+
+| 工具 | 说明 |
+|------|------|
+| `tushare_query` | 通用查询 — 可调用任意 Tushare Pro 接口 |
+| `get_stock_list` | A 股股票列表 |
+| `get_trade_calendar` | 交易日历 |
+| `get_daily_bars` | A 股日线行情（未复权） |
+| `get_daily_basic` | 每日指标：PE/PB/总市值/流通市值/换手率 |
+| `get_income` | 利润表 |
+| `get_balancesheet` | 资产负债表 |
+| `get_cashflow` | 现金流量表 |
+| `get_fina_indicator` | 财务指标（ROE/ROA/毛利率/净利率） |
+| `get_index_daily` | 指数日线行情 |
+| `get_moneyflow` | 个股资金流向 |
+| `get_concept` | 概念股分类 |
+| `get_concept_detail` | 概念股成分 |
+| `get_fund_basic` | 基金列表 |
+| `get_fund_nav` | 基金净值 |
+| `get_shibor` | Shibor 拆借利率 |
+| `get_api_doc` | 按接口名获取完整 API 文档 |
+| `search_api_docs` | 按关键词搜索 API 文档 |
+
+## 维护
+
+```bash
+# 重新爬取 Tushare 文档（如接口更新时）
+python crawl_docs.py
+
+# 重建 API 索引（爬取后需执行）
+python build_index.py
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * tushare-mcp-server CLI launcher
+ * Sets up Python environment and runs the MCP server.
+ */
+
+const { spawn, execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const ROOT = path.resolve(__dirname, "..");
+const SERVER_PY = path.join(ROOT, "server.py");
+const VENV_DIR = path.join(ROOT, ".venv");
+const REQUIREMENTS = path.join(ROOT, "requirements.txt");
+
+function getPython() {
+  // Check venv first
+  const venvPy = path.join(VENV_DIR, "bin", "python");
+  if (fs.existsSync(venvPy)) return venvPy;
+
+  // Check system python
+  for (const cmd of ["python3", "python"]) {
+    try {
+      execSync(`${cmd} --version`, { stdio: "ignore" });
+      return cmd;
+    } catch {}
+  }
+  return null;
+}
+
+function ensureVenv(pythonCmd) {
+  if (fs.existsSync(path.join(VENV_DIR, "bin", "python"))) {
+    return path.join(VENV_DIR, "bin", "python");
+  }
+
+  process.stderr.write("[tushare-mcp] Creating Python venv...\n");
+  execSync(`${pythonCmd} -m venv "${VENV_DIR}"`, { stdio: "inherit" });
+
+  const venvPy = path.join(VENV_DIR, "bin", "python");
+  process.stderr.write("[tushare-mcp] Installing dependencies...\n");
+  execSync(`"${venvPy}" -m pip install --quiet -r "${REQUIREMENTS}"`, {
+    stdio: "inherit",
+  });
+
+  return venvPy;
+}
+
+function main() {
+  let python = getPython();
+
+  if (!python) {
+    process.stderr.write(
+      "[tushare-mcp] Error: Python 3.10+ is required but not found.\n" +
+        "Please install Python from https://www.python.org/downloads/\n"
+    );
+    process.exit(1);
+  }
+
+  // If not using venv python, set up venv
+  if (!python.includes(".venv")) {
+    python = ensureVenv(python);
+  }
+
+  // Check if dependencies are installed
+  try {
+    execSync(`"${python}" -c "import mcp; import httpx"`, { stdio: "ignore" });
+  } catch {
+    process.stderr.write("[tushare-mcp] Installing dependencies...\n");
+    execSync(`"${python}" -m pip install --quiet -r "${REQUIREMENTS}"`, {
+      stdio: "inherit",
+    });
+  }
+
+  // Launch the MCP server
+  const child = spawn(python, [SERVER_PY], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+
+  child.on("exit", (code) => process.exit(code ?? 0));
+  child.on("error", (err) => {
+    process.stderr.write(`[tushare-mcp] Failed to start: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+main();

package/build_index.py

@@ -0,0 +1,159 @@
+"""生成 api_name -> 文档文件名 的结构化映射（含分类与去重）"""
+import json
+import os
+import re
+
+docs_dir = "docs"
+api_index: dict[str, dict] = {}
+
+# ── API 分类映射 ──────────────────────────────────────────────────────
+# 基于 api_name 前缀/精确名称自动分类
+CATEGORY_RULES: list[tuple[str, list[str]]] = [
+    ("沪深股票", ["stock_basic", "stock_company", "stock_st", "stock_hsgt",
+                "stk_ah_comparison", "daily", "weekly", "monthly", "adj_factor",
+                "daily_basic", "daily_info", "suspend_d", "stk_limit",
+                "stk_factor_pro", "stk_premarket", "stk_week_month_adj",
+                "stk_weekly_monthly", "stk_holdernumber", "stk_holdertrade",
+                "stk_managers", "stk_rewards", "stk_surv", "stk_mins",
+                "namechange", "new_share", "repurchase", "bak_daily",
+                "bak_basic", "share_float", "dividend", "bse_mapping",
+                "pro_bar", "rt_k", "rt_min", "limit_list_d"]),
+    ("财务数据", ["income", "balancesheet", "cashflow", "forecast", "express",
+                "fina_indicator", "fina_audit", "fina_mainbz", "disclosure_date"]),
+    ("资金流向", ["moneyflow", "moneyflow_hsgt", "moneyflow_ind_ths",
+                "moneyflow_ind_dc", "moneyflow_mkt_dc", "moneyflow_ths",
+                "moneyflow_dc", "moneyflow_cnt_ths"]),
+    ("市场参考", ["margin", "margin_detail", "margin_secs", "top_list",
+                "top_inst", "block_trade", "hsgt_top10", "ggt_top10",
+                "ggt_daily", "ggt_monthly", "hk_hold", "ccass_hold",
+                "ccass_hold_detail", "slb_len", "hm_list", "hm_detail",
+                "cyq_perf", "cyq_chips", "pledge_stat", "pledge_detail",
+                "broker_recommend", "report_rc", "research_report"]),
+    ("指数数据", ["index_basic", "index_daily", "index_dailybasic",
+                "index_weight", "index_weekly", "index_monthly",
+                "index_classify", "index_member_all", "index_global",
+                "sw_daily", "ci_daily", "ci_index_member"]),
+    ("概念板块", ["concept", "concept_detail", "ths_index", "ths_daily",
+                "ths_member", "dc_index", "dc_member"]),
+    ("基金数据", ["fund_basic", "fund_nav", "fund_div", "fund_portfolio",
+                "fund_daily", "fund_adj", "fund_share", "fund_manager",
+                "fund_company", "fund_sales_ratio", "fund_sales_vol",
+                "etf_basic", "etf_index", "etf_share_size"]),
+    ("期货数据", ["fut_basic", "fut_daily", "fut_holding", "fut_wsr",
+                "fut_settle", "fut_mapping", "fut_weekly_monthly",
+                "ft_limit"]),
+    ("期权数据", ["opt_basic", "opt_daily", "opt_mins"]),
+    ("债券/可转债", ["cb_basic", "cb_issue", "cb_daily", "cb_price_chg",
+                   "cb_share", "cb_call", "cb_rate", "repo_daily", "yc_cb"]),
+    ("港股数据", ["hk_basic", "hk_daily", "hk_tradecal", "hk_mins",
+                "hk_daily_adj", "hk_fina_indicator", "hk_income",
+                "hk_balancesheet", "hk_cashflow"]),
+    ("美股数据", ["us_basic", "us_tradecal", "us_daily", "us_daily_adj",
+                "us_fina_indicator", "us_income", "us_balancesheet",
+                "us_cashflow"]),
+    ("外汇数据", ["fx_obasic", "fx_daily"]),
+    ("宏观经济", ["cn_gdp", "cn_cpi", "cn_m", "cn_ppi", "cn_pmi",
+                "sf_month", "shibor", "shibor_quote", "shibor_lpr",
+                "libor", "hibor", "wz_index", "us_tycr", "npr"]),
+    ("黄金现货", ["sge_basic", "sge_daily"]),
+    ("新闻公告", ["news", "cctv_news", "major_news", "anns_d"]),
+    ("交易日历", ["trade_cal"]),
+]
+
+_name_to_cat = {}
+for cat, names in CATEGORY_RULES:
+    for n in names:
+        _name_to_cat[n] = cat
+
+
+def classify(api_name: str) -> str:
+    if api_name in _name_to_cat:
+        return _name_to_cat[api_name]
+    # 前缀匹配兜底
+    for prefix in ("hk_", "us_", "fut_", "opt_", "cb_", "fx_", "fund_",
+                    "index_", "etf_", "sge_", "cn_"):
+        if api_name.startswith(prefix):
+            for cat, names in CATEGORY_RULES:
+                if any(n.startswith(prefix) for n in names):
+                    return cat
+    return "其他"
+
+
+for f in sorted(os.listdir(docs_dir)):
+    if not f.endswith(".md") or f.startswith("_"):
+        continue
+    path = os.path.join(docs_dir, f)
+    content = open(path, encoding="utf-8").read()
+
+    # 提取标题
+    title_m = re.match(r"^# (.+)", content)
+    title = title_m.group(1).strip() if title_m else f[5:-3]
+
+    # 提取 doc_id
+    docid_m = re.search(r"文档ID:\s*(\d+)", content)
+    doc_id = int(docid_m.group(1)) if docid_m else 0
+
+    # 提取接口名（处理 "接口：" 和 "接口名称：" 等格式，含 markdown 粗体和转义 \_）
+    api_name = None
+    for pat in (r"接口[：:]\s*([\w\\_]+)",
+                r"\*{0,2}接口名称\*{0,2}\s*[：:]\s*([\w\\_]+)",
+                r"\*{0,2}接口说明\*{0,2}\s*[：:]\s*([\w\\_]+)"):
+        m = re.search(pat, content)
+        if m:
+            api_name = m.group(1).replace("\\_", "_").replace("\\", "")
+            break
+
+    # 提取描述
+    desc = ""
+    desc_m = re.search(r"描述[：:]\s*(.+)", content)
+    if desc_m:
+        desc = desc_m.group(1).strip()[:120]
+
+    entry = {
+        "title": title,
+        "doc_id": doc_id,
+        "description": desc,
+        "file": f,
+        "category": classify(api_name) if api_name else "其他",
+    }
+
+    if api_name:
+        # 重复 key 冲突：保留 doc_id 较小的（通常是 A 股 / 主版本）
+        if api_name in api_index:
+            existing = api_index[api_name]
+            if doc_id < existing["doc_id"]:
+                # 新条目是主版本，将旧条目用 title 后缀做别名
+                alias = f"{api_name}_{existing['file'][5:-3].split('_', 1)[-1]}" if '_' in existing['file'] else f"{api_name}_{existing['doc_id']}"
+                # 简化: 用类别区分
+                alias = f"{api_name}__{''.join(existing['title'].split()[:2])}"
+                api_index[alias] = existing
+                api_index[api_name] = entry
+            else:
+                alias = f"{api_name}__{''.join(title.split()[:2])}"
+                api_index[alias] = entry
+        else:
+            api_index[api_name] = entry
+    else:
+        api_index[f"_doc_{doc_id}"] = entry
+
+out_path = os.path.join(docs_dir, "_api_index.json")
+with open(out_path, "w", encoding="utf-8") as fh:
+    json.dump(api_index, fh, ensure_ascii=False, indent=2)
+
+# 统计
+cats = {}
+for k, v in api_index.items():
+    c = v.get("category", "其他")
+    cats[c] = cats.get(c, 0) + 1
+
+print(f"索引已生成: {len(api_index)} 个条目 -> {out_path}")
+print(f"\n分类统计:")
+for c in sorted(cats, key=lambda x: -cats[x]):
+    print(f"  {c:12s}: {cats[c]} 个")
+
+# 显示冲突处理结果
+print(f"\n别名条目 (冲突解决):")
+for k in sorted(api_index):
+    if "__" in k:
+        v = api_index[k]
+        print(f"  {k:40s} -> {v['title']} (doc_id={v['doc_id']})")