@tushare/mcp

@tushare/mcp

Tushare Model Context Protocol 服务器 - 为 AI 工具提供 100+ 金融数据接口

功能特性

• 三个核心工具：sdk_call（通用调用）、sdk_schema（参数查询）、sdk_search（接口搜索）
• MCP 资源：sdk:apis（接口列表）、sdk:api/<name>（详细说明）
• 顺序分页：自动处理大数据量查询（顺序分页 + 重试/退避）
• 字段预设：minimal/basic/full 三档预设，减少数据传输
• 限流重试：内置指数退避重试，遵循 Tushare API 限制
• 强类型安全：基于 @tushare/sdk，严格类型检查，零 any

快速开始

安装

# 在 monorepo 中
pnpm install

# 构建
pnpm build

配置

设置 Tushare API Token：

export TUSHARE_TOKEN="your_tushare_token_here"

说明：也支持使用 TUSHARE_API_TOKEN 或 TS_TOKEN 作为别名环境变量。

运行

# 开发模式
pnpm dev

# 生产模式
tushare-mcp --stdio

MCP 客户端配置

在 ~/.codeium/windsurf/mcp_config.json 中添加：

{
  "mcpServers": {
    "tushare": {
      "command": "npx",
      "args": [
        "@tushare/mcp",
        "--stdio"
      ],
      "env": {
        "TUSHARE_TOKEN": "your_token_here"
      }
    }
  }
}

工具使用

sdk_search - 搜索接口

{
  "name": "sdk_search",
  "arguments": {
    "q": "股票日线数据",
    "limit": 5
  }
}

sdk_schema - 查看参数

{
  "name": "sdk_schema", 
  "arguments": {
    "api_name": "daily"
  }
}

sdk_call - 调用接口

{
  "name": "sdk_call",
  "arguments": {
    "api_name": "daily",
    "params": {
      "ts_code": "000001.SZ",
      "start_date": "20240101",
      "end_date": "20240331"
    },
    "fields_preset": "basic"
  }
}

环境变量

变量	默认值	说明
TUSHARE_TOKEN	-	必填 Tushare API Token
TUSHARE_MCP_POPULAR_TOOLS	20	热门工具数量（0=关闭）
TUSHARE_MCP_MAX_CONCURRENCY	1	最大并发数
TUSHARE_MCP_TIMEOUT_MS	30000	请求超时（毫秒）
TUSHARE_MCP_RETRY	3	最大重试次数
TUSHARE_MCP_BACKOFF_MS	200	退避基础毫秒数
TUSHARE_MCP_VERBOSE	false	详细日志
TUSHARE_MCP_STDIO	true	是否启用 STDIO 传输模式

工具详解：sdk_call

sdk_call 是通用调用器，对应 src/tools/call.ts 的 Schema。参数如下（蛇形命名）：

• api_name（string，必填）：接口名，例如 stock_basic、daily。
• params（object，必填）：入参对象；具体字段请通过 sdk_schema 查询。
• fields（string[]，可选）：返回字段列表；不传则返回所有字段。
• fields_preset（'minimal' | 'basic' | 'full'）：字段预设包。
• paginate（boolean，默认 false）：是否自动顺序分页抓取。
• limit（integer，默认 5000，1..5000）：单次请求条数上限。
• offset（integer，默认 0，>=0）：分页偏移量。
• max_rows（integer，默认 50000，1..100000）：分页模式下最多累计条数。
• transform（'object' | 'raw'，默认 'object'）：返回对象数组或原始二维表。

字段选择规则：fields_preset 与 fields 会做并集并去重；未指定则等同于“全部字段”。

示例（单次调用）：

{
  "api_name": "stock_basic",
  "params": { "limit": 3 },
  "fields": ["ts_code", "name"]
}

示例（顺序分页，最多 1 万行）：

{
  "api_name": "daily",
  "params": { "ts_code": "000001.SZ", "start_date": "20240101" },
  "paginate": true,
  "limit": 5000,
  "max_rows": 10000,
  "fields_preset": "basic",
  "transform": "object"
}

字段预设

• minimal：核心字段（3-5个），适合快速查看
• basic：常用字段（8-12个），适合大多数分析
• full：所有字段，等同于不指定 fields

常用 API

分类	API	说明
股票	stock_basic	股票基础信息
股票	daily	日线数据
股票	daily_basic	每日基本面
基金	fund_basic	基金基础信息
基金	fund_nav	基金净值
财务	income	利润表
财务	balancesheet	资产负债表
指数	index_daily	指数日线

开发

项目结构

src/
├── cli.ts              # CLI 入口
├── server.ts           # MCP 服务器
├── env.ts              # 配置管理
├── types.ts            # 类型定义
├── errors.ts           # 错误处理
├── caller.ts           # SDK 调用器
├── schema.ts           # Schema 管理
├── search.ts           # 搜索引擎
├── resources.ts        # 资源处理
├── presets.ts          # 字段预设
├── rateLimit.ts        # 限流重试
└── tools/              # 工具实现
    ├── call.ts         # sdk_call
    ├── schema.ts       # sdk_schema
    └── search.ts       # sdk_search

命令

# 类型检查
pnpm typecheck

# 测试
pnpm test

# 构建
pnpm build

# 清理
pnpm clean

License

MIT - 详见 LICENSE