MCP 使用指南

本指南将帮助你在 AI 客户端(如 Claude Desktop)中配置和使用 Tushare MCP 服务,实现 AI 助手直接查询 A 股市场数据的能力。

预计完成时间: 15 分钟 前置要求: Node.js 18+, 有效的 Tushare API Token

什么是 MCP

MCP(Model Context Protocol,模型上下文协议) 是一个开源标准协议,用于连接 AI 应用程序与外部系统。它就像 AI 应用的"USB-C 接口",为 AI 模型提供标准化的方式来访问数据源(如 Google Calendar、Notion)和工具(如搜索引擎、计算器)。通过 MCP,开发者可以构建个性化的 AI 助手、企业聊天机器人、AI 驱动的设计和创作工具,使 AI 能够安全、可控地与各种系统和工作流程集成。

MCP 核心概念

Servers(服务器): 暴露数据和工具的系统,如本项目的 Tushare MCP 服务
Clients(客户端): 连接到服务器的 AI 应用程序,如 Claude Desktop
Resources(资源): 数据源,如日历、文档、数据库
Tools(工具): 外部系统功能,如搜索、计算、API 调用

Tushare MCP 服务

Tushare MCP 服务是基于 MCP 协议实现的 A 股市场数据服务器,为 AI 模型提供以下能力:

📈 查询实时股票行情
💰 查询公司财务报表
📊 查询历史 K 线数据
📉 查询市场指数行情

前置要求

在开始之前,请确保你已具备以下条件:

1. Node.js 环境

版本要求: Node.js 18.0.0 或更高版本
安装验证: 运行 node --version 检查版本

如果尚未安装 Node.js,请访问 Node.js 官网下载安装。

2. Tushare API Token

Tushare API Token 是访问 Tushare Pro 数据的唯一凭证。

获取步骤:

访问 Tushare Pro 注册页面注册账号
登录后进入个人中心
点击"接口 TOKEN"复制你的 Token

积分说明: 新注册用户有 100 积分,可以查询基础数据。部分高级数据需要更高积分等级。详见 Tushare 积分规则。

3. 支持 MCP 的 AI 客户端

本指南重点介绍主流 MCP 客户端的配置,支持以下客户端:

Claude Desktop ⭐ 推荐 - 图形界面客户端
Claude Code ⭐ 推荐 - 官方 CLI 工具,支持快捷命令
Cursor - AI 代码编辑器
VSCode with Cline - VSCode 扩展
Zed Editor - 轻量级编辑器

更多客户端请查看 MCP 客户端总览。

安装

Tushare MCP 服务支持两种部署方式:

方式 1: 通过 npm 安装(推荐)

适用于生产使用和快速体验。

1# 使用 pnpm
2pnpm add -g @hestudy/tushare-mcp
3
4# 使用 npm
5npm install -g @hestudy/tushare-mcp

方式 2: 本地开发

适用于需要修改源码或参与开发的场景。

1# 克隆仓库
2git clone https://github.com/hestudy/tushare-sdk.git
3cd tushare-sdk
4
5# 安装依赖
6pnpm install
7
8# 构建 MCP 服务
9cd apps/tushare-mcp
10pnpm build

构建完成后,服务入口文件位于 apps/tushare-mcp/dist/index.js。

配置

Claude Desktop 配置

Claude Desktop 是使用 MCP 服务最便捷的方式,以下是详细配置步骤。

步骤 1: 找到配置文件

根据你的操作系统,配置文件位于:

操作系统	配置文件路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json` 或`C:\Users\你的用户名\AppData\Roaming\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

快捷访问: 打开 Claude Desktop → 设置 → Developer → 点击 "Edit Config" 按钮

步骤 2: 编辑配置文件

使用 npx 方式(推荐)

无需预先安装,每次启动时自动下载最新版本:

1{
2  "mcpServers": {
3    "tushare": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "@hestudy/tushare-mcp@latest"
8      ],
9      "env": {
10        "TUSHARE_TOKEN": "your_tushare_token_here"
11      }
12    }
13  }
14}

使用本地开发方式

适用于需要调试或修改源码的场景:

1{
2  "mcpServers": {
3    "tushare": {
4      "command": "node",
5      "args": [
6        "/Users/your-username/path/to/tushare-sdk/apps/tushare-mcp/dist/index.js"
7      ],
8      "env": {
9        "TUSHARE_TOKEN": "your_tushare_token_here"
10      }
11    }
12  }
13}

重要提示:

将 your_tushare_token_here 替换为你的实际 Tushare Token
本地开发方式需要使用绝对路径
Windows 用户路径示例: C:\\Users\\your-username\\tushare-sdk\\apps\\tushare-mcp\\dist\\index.js(注意双反斜杠)

步骤 3: 重启 Claude Desktop

保存配置文件后,完全退出 Claude Desktop 并重新启动,新配置才会生效。

验证方法: 在 Claude 对话中输入 "你现在可以使用哪些工具?",如果看到 Tushare 相关工具,说明配置成功。

Claude Code 配置

Claude Code 是 Anthropic 推出的官方 CLI 工具,支持通过命令行快速添加和管理 MCP 服务器。

使用命令行添加(推荐)

在终端中直接运行以下命令即可添加 Tushare MCP 服务器:

1claude mcp add --transport stdio tushare \
2  --env TUSHARE_TOKEN=your_tushare_token_here \
3  -- npx -y @hestudy/tushare-mcp@latest

命令参数说明:

参数	说明
`--transport stdio`	使用标准输入输出传输协议(stdio)
`tushare`	MCP 服务器名称,可以自定义
`--env TUSHARE_TOKEN=...`	设置环境变量,配置 Tushare API Token
`--`	分隔符,后面跟服务器启动命令
`npx -y @hestudy/tushare-mcp@latest`	服务器启动命令,使用 npx 运行

本地开发方式:

如果您在本地开发 Tushare SDK,可以指定本地路径:

1claude mcp add --transport stdio tushare \
2  --env TUSHARE_TOKEN=your_tushare_token_here \
3  -- node /absolute/path/to/tushare-sdk/apps/tushare-mcp/dist/index.js

注意: Windows 用户需要使用反斜杠路径,如 C:\Users\username\tushare-sdk\...

管理 MCP 服务器

Claude Code 提供了一组命令来管理 MCP 服务器:

1# 查看所有已配置的 MCP 服务器
2claude mcp list
3
4# 查看特定服务器的详细信息
5claude mcp get tushare
6
7# 删除 MCP 服务器
8claude mcp remove tushare

配置文件

如果您更喜欢手动编辑配置文件,可以直接修改:

配置文件位置:

macOS/Linux: ~/.config/claude/mcp.json
Windows: %APPDATA%\Claude\mcp.json

配置内容:

1{
2  "mcpServers": {
3    "tushare": {
4      "command": "npx",
5      "args": ["-y", "@hestudy/tushare-mcp@latest"],
6      "env": {
7        "TUSHARE_TOKEN": "your_tushare_token_here"
8      }
9    }
10  }
11}

高级配置选项

Claude Code 支持额外的配置选项:

1# 指定配置范围(local/project/user)
2claude mcp add --scope user --transport stdio tushare \
3  --env TUSHARE_TOKEN=your_token \
4  -- npx -y @hestudy/tushare-mcp@latest
5
6# 添加多个环境变量
7claude mcp add --transport stdio tushare \
8  --env TUSHARE_TOKEN=your_token \
9  --env LOG_LEVEL=debug \
10  -- npx -y @hestudy/tushare-mcp@latest

配置范围说明:

local: 当前项目配置(.claude/mcp.json)
project: 项目级配置
user: 用户级全局配置(默认)

验证配置

添加完成后,可以通过以下方式验证:

1# 查看服务器状态
2claude mcp get tushare
3
4# 启动 Claude Code 会话
5claude
6
7# 在对话中询问
8"你现在可以使用哪些工具?"

如果看到 Tushare 相关工具(query_stock_quote、query_financial 等),说明配置成功。

其他客户端配置

配置文件位置:

全局配置: ~/.cursor/mcp.json
项目配置: <project-root>/.cursor/mcp.json

配置内容 (与 Claude Desktop 相同):

1{
2  "mcpServers": {
3    "tushare": {
4      "command": "npx",
5      "args": ["-y", "@hestudy/tushare-mcp@latest"],
6      "env": {
7        "TUSHARE_TOKEN": "your_tushare_token_here"
8      }
9    }
10  }
11}

配置方式:

点击 Cline 面板顶部的 "MCP Servers" 图标
选择 "Installed" 标签
点击 "Configure MCP Servers"
添加以下配置

配置文件: cline_mcp_settings.json

1{
2  "mcpServers": {
3    "tushare": {
4      "command": "npx",
5      "args": ["-y", "@hestudy/tushare-mcp@latest"],
6      "env": {
7        "TUSHARE_TOKEN": "your_tushare_token_here"
8      }
9    }
10  }
11}

提示: Cline 支持单独启用/禁用每个 MCP 服务器。

配置文件: settings.json

访问方式: Cmd/Ctrl + , 或运行命令 zed: open settings

配置内容:

1{
2  "context_servers": {
3    "tushare": {
4      "command": "npx",
5      "args": ["-y", "@hestudy/tushare-mcp@latest"],
6      "env": {
7        "TUSHARE_TOKEN": "your_tushare_token_here"
8      }
9    }
10  }
11}

更多客户端的配置方式,请参考 MCP 官方文档。

可用工具

Tushare MCP 服务提供以下 4 个工具,可在 AI 对话中自动调用。

1. query_stock_quote - 股票行情查询

查询实时股票行情数据,包括最新价、涨跌幅、成交量等。

参数说明:

参数名	是否必填	类型	说明	示例值
ts_code	✅ 必需	string	股票代码,格式如 '600519.SH'(上交所)或 '000001.SZ'(深交所)	`600519.SH`
trade_date	⚪ 可选	string	交易日期,格式如 '20251014',不填则返回最新数据	`20251014`

示例参数:

1{
2  "ts_code": "600519.SH",
3  "trade_date": "20251014"
4}

2. query_financial - 财务数据查询

查询公司财务报表数据,支持利润表、资产负债表、现金流量表。

参数说明:

参数名	是否必填	类型	说明	示例值
ts_code	✅ 必需	string	股票代码	`600519.SH`
period	✅ 必需	string	报告期,格式如 '20231231'(季度末日期)	`20231231`
report_type	✅ 必需	string	报表类型: "income"(利润表), "balance"(资产负债表), "cashflow"(现金流量表)	`income`

示例参数:

1{
2  "ts_code": "600519.SH",
3  "period": "20231231",
4  "report_type": "income"
5}

3. query_kline - K线数据查询

查询历史 K 线数据,支持日线、周线、月线。

参数说明:

参数名	是否必填	类型	说明	示例值
ts_code	✅ 必需	string	股票代码	`600519.SH`
start_date	✅ 必需	string	开始日期,格式如 '20251001'	`20251001`
end_date	✅ 必需	string	结束日期,格式如 '20251014'	`20251014`
freq	⚪ 可选	string	K线频率: "D"(日线), "W"(周线), "M"(月线),默认 "D"	`D`

示例参数:

1{
2  "ts_code": "600519.SH",
3  "start_date": "20251001",
4  "end_date": "20251014",
5  "freq": "D"
6}

4. query_index - 市场指数查询

查询市场指数行情数据,如上证指数、深证成指、创业板指等。

参数说明:

参数名	是否必填	类型	说明	示例值
ts_code	✅ 必需	string	指数代码,如 '000001.SH'(上证指数)	`000001.SH`
trade_date	⚪ 可选	string	交易日期,格式如 '20251014'	`20251014`

常用指数代码:

000001.SH: 上证指数
399001.SZ: 深证成指
399006.SZ: 创业板指
000300.SH: 沪深300
000016.SH: 上证50

示例参数:

1{
2  "ts_code": "000001.SH",
3  "trade_date": "20251014"
4}

使用示例

以下是典型的使用场景示例,展示如何在 AI 对话中使用 Tushare MCP 服务。

示例 1: 查询股票行情

用户提问:

"帮我查询贵州茅台 (600519.SH) 最新的股票行情"

AI 工具调用:

AI 会自动调用 query_stock_quote 工具:

1{
2  "tool": "query_stock_quote",
3  "parameters": {
4    "ts_code": "600519.SH"
5  }
6}

返回数据示例:

AI 会收到类似以下的数据并为你分析:

字段	值
股票代码	600519.SH
股票名称	贵州茅台
最新价	1680.50 元
涨跌幅	+1.23%
成交量	1,234,567 股
成交额	20.8 亿元

示例 2: 查询财务数据

用户提问:

"查询平安银行 2023 年年报的利润表数据"

AI 工具调用:

1{
2  "tool": "query_financial",
3  "parameters": {
4    "ts_code": "000001.SZ",
5    "period": "20231231",
6    "report_type": "income"
7  }
8}

返回数据示例:

财务指标	金额(亿元)
营业总收入	1,856.32
营业利润	523.45
利润总额	530.12
净利润	450.87

示例 3: 查询 K 线数据

用户提问:

"获取上证指数最近一个月的日线数据"

AI 工具调用:

1{
2  "tool": "query_kline",
3  "parameters": {
4    "ts_code": "000001.SH",
5    "start_date": "20250914",
6    "end_date": "20251014",
7    "freq": "D"
8  }
9}

返回数据示例:

AI 会收到 20+ 条 K 线数据,包含:

字段	说明
trade_date	交易日期
open	开盘价
high	最高价
low	最低价
close	收盘价
volume	成交量

AI 可以基于这些数据分析趋势、计算涨跌幅等。

进阶配置

环境变量说明

除了 TUSHARE_TOKEN,还可以配置以下环境变量:

环境变量	说明	默认值	示例
`TUSHARE_TOKEN`	Tushare API Token	(必需)	`your_token_here`
`LOG_LEVEL`	日志级别	`info`	`debug` / `info` / `warn` / `error`
`RATE_LIMIT_MAX_REQUESTS`	限流:最大请求数	`100`	`200`
`RATE_LIMIT_WINDOW_MS`	限流:时间窗口(毫秒)	`60000`	`60000`

调整限流参数

如果你的 Tushare 积分等级较高,可以调整限流参数提升性能:

1{
2  "mcpServers": {
3    "tushare": {
4      "command": "npx",
5      "args": ["-y", "@hestudy/tushare-mcp@latest"],
6      "env": {
7        "TUSHARE_TOKEN": "your_token",
8        "RATE_LIMIT_MAX_REQUESTS": "200",
9        "RATE_LIMIT_WINDOW_MS": "60000"
10      }
11    }
12  }
13}

积分等级参考:

100 积分: 1 次/秒 (默认配置已足够)
2000 积分: 5 次/秒 (可设置 MAX_REQUESTS=300)
5000 积分: 20 次/秒 (可设置 MAX_REQUESTS=1200)

调试日志

如需查看详细的调试日志,设置 LOG_LEVEL=debug:

1{
2  "env": {
3    "TUSHARE_TOKEN": "your_token",
4    "LOG_LEVEL": "debug"
5  }
6}

日志文件位置:

macOS/Linux: ~/Library/Logs/Claude/mcp-server-tushare.log
Windows: %APPDATA%\Claude\Logs\mcp-server-tushare.log

常见问题

Q1: Token 无效或认证失败

错误信息: "Authentication failed" 或 "Invalid token"

解决方案:

检查 Token 是否正确复制(无多余空格)
访问 Tushare Pro 登录账号,在个人中心确认 Token
如果 Token 已泄露,可以在个人中心点击"刷新"生成新 Token
确认账号状态是否正常(未被封禁)

Q2: 配置文件找不到或修改不生效

问题描述: 找不到配置文件,或者修改后没有效果

解决方案:

找不到文件: 参考本文档"配置"章节的路径表格,确保路径正确
- macOS: ~/Library/Application Support/Claude/ (注意 Library 是隐藏文件夹)
- Windows: 在文件管理器地址栏输入 %APPDATA%\Claude
修改不生效: 确保完全退出 Claude Desktop(不是最小化),然后重新启动
JSON 格式错误: 使用 JSON 验证工具检查配置文件语法是否正确

Q3: MCP 服务启动失败

错误信息: "Failed to start MCP server" 或连接超时

解决方案:

Node.js 版本: 确认 Node.js 版本 >= 18.0.0 (node --version)
网络问题: npx 方式需要联网下载,确保网络畅通
路径问题: 本地开发方式需要使用绝对路径,检查路径是否正确
查看日志: 设置 LOG_LEVEL=debug 并查看日志文件定位问题

Q4: 查询返回空数据

问题描述: 工具调用成功,但返回的数据为空

可能原因:

非交易日: 查询的日期是周末或节假日,没有交易数据
参数格式错误: 检查日期格式是否为 YYYYMMDD(如 20251014)
股票代码错误: 确认股票代码格式正确(如 600519.SH 而非 600519)
积分不足: 某些高级数据(如每日指标)需要更高的积分等级

解决方案: 先查询交易日历确认是否为交易日,然后检查参数格式

Q5: 如何查看 AI 调用了哪些工具?

方法:

在 Claude 对话中直接询问: "你刚才调用了哪些工具?"
查看 Claude Desktop 的 Developer 面板(如果支持)
设置 LOG_LEVEL=debug 查看详细日志

Q6: 支持哪些 AI 客户端?

官方支持:

Claude Desktop (推荐)
Cursor
VSCode with Cline
Zed Editor

理论支持: 所有符合 MCP 协议标准的客户端都应该可以使用,具体配置方式可能有差异。

更多问题请访问 GitHub Issues。

MCP 使用指南#

什么是 MCP#

MCP 核心概念#

Tushare MCP 服务#

前置要求#

1. Node.js 环境#

2. Tushare API Token#

3. 支持 MCP 的 AI 客户端#

安装#

方式 1: 通过 npm 安装(推荐)#

方式 2: 本地开发#

配置#

Claude Desktop 配置#

步骤 1: 找到配置文件#

步骤 2: 编辑配置文件#

使用 npx 方式(推荐)#

使用本地开发方式#

步骤 3: 重启 Claude Desktop#

Claude Code 配置#

使用命令行添加(推荐)#

管理 MCP 服务器#

配置文件#

高级配置选项#

验证配置#

其他客户端配置#

可用工具#

1. query_stock_quote - 股票行情查询#

2. query_financial - 财务数据查询#

3. query_kline - K线数据查询#

4. query_index - 市场指数查询#

使用示例#

示例 1: 查询股票行情#

示例 2: 查询财务数据#

示例 3: 查询 K 线数据#

更多使用技巧#

进阶配置#

环境变量说明#

调整限流参数#

调试日志#

常见问题#

Q1: Token 无效或认证失败#

Q2: 配置文件找不到或修改不生效#

Q3: MCP 服务启动失败#

Q4: 查询返回空数据#

Q5: 如何查看 AI 调用了哪些工具?#

Q6: 支持哪些 AI 客户端?#

相关链接#

官方资源#

Tushare Pro#

AI 客户端#

本项目#

MCP 使用指南

什么是 MCP

MCP 核心概念

Tushare MCP 服务

前置要求

1. Node.js 环境

2. Tushare API Token

3. 支持 MCP 的 AI 客户端

安装

方式 1: 通过 npm 安装(推荐)

方式 2: 本地开发

配置

Claude Desktop 配置

步骤 1: 找到配置文件

步骤 2: 编辑配置文件

使用 npx 方式(推荐)

使用本地开发方式

步骤 3: 重启 Claude Desktop

Claude Code 配置

使用命令行添加(推荐)

管理 MCP 服务器

配置文件

高级配置选项

验证配置

其他客户端配置

可用工具

1. query_stock_quote - 股票行情查询

2. query_financial - 财务数据查询

3. query_kline - K线数据查询

4. query_index - 市场指数查询

使用示例

示例 1: 查询股票行情

示例 2: 查询财务数据

示例 3: 查询 K 线数据

更多使用技巧

进阶配置

环境变量说明

调整限流参数

调试日志

常见问题

Q1: Token 无效或认证失败

Q2: 配置文件找不到或修改不生效

Q3: MCP 服务启动失败

Q4: 查询返回空数据

Q5: 如何查看 AI 调用了哪些工具?

Q6: 支持哪些 AI 客户端?

相关链接

官方资源

Tushare Pro

AI 客户端

本项目