bitget-agent-mcp

bitget-agent-mcp — Bitget 官方 MCP 交易服务

通过模型上下文协议，将 Claude Desktop、Cursor、Continue、Windsurf 和 ChatGPT 连接到 Bitget，用自然语言交易加密货币。

快速开始 · 功能 · 工作原理 · 安装 · 配置 · 安全 · 故障排查 · 常见问题

---

概述

bitget-agent-mcp 是 Bitget 的官方模型上下文协议（MCP）服务，可让 Claude Desktop、Cursor、Continue、Windsurf 和 ChatGPT Desktop 等桌面 AI Agent 通过自然语言指令操作你的 Bitget 账户。

它基于 Bitget 统一交易账户（UTA / v3）API 构建，涵盖市场数据、现货、期货、账户与资金管理、子账户、贷款和税务等领域的 89 项交易操作。关键在于，它不会针对每个端点都向大模型提供一个工具，而是提供一组精简的、可渐进发现的意图接口，包含 14 个精选意图动词（默认配置加载 12 个动词，加上 discover 和 raw，共 14 个工具），让 AI 宿主获得完整功能，同时避免端点一工具式服务常见的上下文膨胀和工具选择错误。

隶属于 Bitget Agent Hub —— Bitget 官方开源 AI 生态系统，包含 CLI、SDK、安装程序和市场分析技能。

---

快速开始

前置条件

• Node.js ≥ 20（下载）
• Bitget API Key（在此创建）——启用 Read 和 Trade 权限
• 支持 MCP 的 AI 宿主（Claude Desktop、Cursor、Continue、Windsurf、ChatGPT Desktop，或任何 stdio MCP 客户端）

一步安装（推荐）

将此提示词粘贴到你的 AI Agent（Claude Desktop / Cursor / 等）中：

Please configure the Bitget MCP Server for my AI tool (requires Node.js 20+):
first ask me which AI tool I use (Claude Desktop / Cursor / Windsurf / ChatGPT
Desktop), then add a server that runs `npx -y @bitget-ai/bitget-agent-mcp` to
that tool's MCP config, with BITGET_API_KEY, BITGET_SECRET_KEY, and
BITGET_PASSPHRASE filled in. Confirm once the Bitget tools have loaded.

Agent 将检测你的工具、添加 npx 服务条目、配置凭据并验证连接。

手动安装

更喜欢自己编辑配置文件？跳转到配置，查看各工具的 JSON 代码片段。命令始终为：

npx -y @bitget-ai/bitget-agent-mcp

---

你可以做什么

配置完成后，你的 AI 就能通过自然语言原生使用 Bitget 的交易体系。以下是几个示例（每个示例都对应可用接口中的一项真实操作）：

向 AI 提问	执行的操作	凭据
"当前 BTC 价格是多少？"	通过 market 动词获取实时行情	❌ 否
"获取 BTC 的 4h K 线"	通过 market 获取 OHLCV / K 线历史数据	❌ 否
"BTC 永续合约的资金费率是多少？"	通过 market 获取资金费率	❌ 否
"显示我所有账户的 USDT 余额"	通过 account_overview 查看账户概览	✅ 是
"以市价买入 0.1 BTC"	通过 order 下达现货市价单	✅ 是
"将杠杆设为 10x 并开立 BTC 多仓"	account_config + order / position	✅ 是
"列出我的未成交订单"	order（open）	✅ 是
"将 500 USDT 从现货账户划转到期货账户"	通过 transfer_funds 进行内部划转	✅ 是
"取消我所有未成交订单"	order（cancelAll）——高风险操作，需要确认	✅ 是
"以抵押品借入 USDT"	通过 loan 办理加密货币借贷	✅ 是

市场数据（market 动词）是公开的，无需 API 凭据即可使用；所有涉及你账户的操作都需要密钥。

高级模式

• --read-only — 阻止会话中的所有写入操作。动词仍然可见，但任何下单、划转、取消或提现操作都会在到达 Bitget 前被拒绝。适合安全探索。（不能与 --paper-trading 同时使用。）
• --paper-trading — 将签名请求发送到 Bitget 的模拟交易环境（添加 paptrading: 1 请求头）。需要单独的模拟 API 密钥。非常适合零风险演练策略。
• --modules <list> — 仅加载所需模块。默认值：account,trade,market。可按需加载：strategy、cryptoloans、tax。
• --surface <intent|full> — intent（默认）提供精选的动词。full 还会为每个底层 v3 端点提供一个工具。

---

Agent 如何使用

意图接口支持渐进式发现。Agent 无需预先读取所有架构，而是按发现 → 深入了解 → 执行的流程进行：

discover({})                                   → list business domains + meta-tools
discover({ domain: "trade" })                  → that domain's verbs, one line each
discover({ tool: "order" })                    → one verb's full input schema (+ its actions)
discover({ tool: "order", action: "place" })   → one action's exact required/optional contract
order({ action: "place", ... })                → execute

如果提示词已明确指出动词和参数，Agent 就会跳过发现步骤，直接调用。领域未知时，discover({ search: "funding" }) 会对整个接口进行关键词搜索。以下两个元工具始终可用：

• discover — 对接口进行渐进式探索。
• raw — 可通过 operationId 调用任意 v3 操作的备用入口，用于处理长尾需求。（实际上，每项操作也都可以通过某个动词完成，因此很少需要使用 raw。）

写入安全

• 普通写入会立即执行。
• 高风险 / 不可逆操作（例如 cancelAll、withdraw）会返回 { confirmationRequired: true }，除非你传入 confirm: true。
• 任何写入操作都接受 dryRun: true，可预览待发送的请求，而不会实际发送。

MCP 工具注释根据 SDK 的 riskLevel（read / write / high）生成，因此宿主可以在模型调用破坏性操作前将其标记出来。

---

架构

graph TD
    A[AI Host<br/>Claude Desktop / Cursor / …] -->|MCP over stdio| B[bitget-agent-mcp<br/>thin protocol adapter]
    B --> S[@bitget-ai/bitget-agent-sdk<br/>intent verbs · discover · raw<br/>write-safety gate · HMAC signing · retry]
    S -->|HMAC-SHA256 signed| C[Bitget UTA v3 REST API<br/>api.bitget.com]
    D[Environment Variables<br/>BITGET_API_KEY etc.] --> B
    style B fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px

工作原理：

1. 你的 AI 宿主通过 npx 在本地使用 stdio 启动 MCP 服务——不会监听网络，也不使用代理。
2. 凭据通过宿主配置中的环境变量传入；服务绝不会存储、记录或代理这些凭据。
3. 所有经过身份验证的请求都在进程内使用 HMAC-SHA256 签名，并直接发送到 Bitget 官方 API。
4. 响应通过 MCP 返回到你的 AI 对话中。

所有“智能”功能——发现、意图路由、写入安全门控、签名和响应处理——都由 @bitget-ai/bitget-agent-sdk 提供。此软件包是在其之上的轻量级 stdio 适配器。

---

安装

支持的 AI Host

AI Host	状态	说明
Claude Desktop	✅	一流支持，通过 claude_desktop_config.json 配置
Cursor	✅	默认配置文件符合 40 个工具的上限，且留有充足余量
Continue	✅	VS Code / JetBrains 扩展
ChatGPT Desktop	✅	OpenAI 的桌面客户端
Windsurf	✅	Codeium 的 AI IDE
任何 MCP 客户端	✅	任何通过 stdio 使用 MCP 的客户端

分步设置

1. 获取 API 密钥

1. 登录 bitget.com
2. 前往 个人资料 → API 管理
3. 点击 创建 API 密钥
4. 启用 读取 和 交易 权限
5. 复制以下三个值：API Key、Secret Key、Passphrase

⚠️ 安全提示： 请妥善保管这些信息。切勿分享或将其提交到版本控制系统。

2. 配置你的 Host

使用一步设置提示词，或手动将服务添加到 Host 的 MCP 配置中（参见配置）。

3. 验证

向你的 AI 提问：“有哪些 Bitget 工具可用？” 你应该会看到 market、order、position、account_overview 等动词，以及 discover 和 raw。

---

配置

Claude Desktop

编辑 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitget": {
      "command": "npx",
      "args": ["-y", "@bitget-ai/bitget-agent-mcp"],
      "env": {
        "BITGET_API_KEY": "your-api-key-here",
        "BITGET_SECRET_KEY": "your-secret-key-here",
        "BITGET_PASSPHRASE": "your-passphrase-here"
      }
    }
  }
}

保存后重启 Claude Desktop。

Cursor

设置 → MCP → 添加新服务：

字段	值
命令	npx
参数	-y @bitget-ai/bitget-agent-mcp
环境变量	BITGET_API_KEY、BITGET_SECRET_KEY、BITGET_PASSPHRASE

⚠️ Cursor 工具数量限制： Cursor 对所有服务中的 MCP 工具总数设有 40 个上限。默认的 Bitget 配置文件会加载 14 个工具（12 个意图动词 + discover + raw），为其他服务留出 26 个位置。--modules all 会加载 16 个工具。

Continue / Windsurf / ChatGPT Desktop / 其他 MCP Host

使用相同的 npx -y @bitget-ai/bitget-agent-mcp 命令，并按照工具的 MCP 配置文档通过环境变量传递凭据。只要 Host 支持通过 stdio 使用 MCP，即可正常工作。

自定义配置示例

只读模式（适合安全探索）：

{ "args": ["-y", "@bitget-ai/bitget-agent-mcp", "--read-only"] }

模拟交易（Demo 环境 — 使用 Demo API 密钥）：

{
  "args": ["-y", "@bitget-ai/bitget-agent-mcp", "--paper-trading"],
  "env": {
    "BITGET_API_KEY": "your-demo-api-key",
    "BITGET_SECRET_KEY": "your-demo-secret-key",
    "BITGET_PASSPHRASE": "your-demo-passphrase"
  }
}

加载额外模块：

{ "args": ["-y", "@bitget-ai/bitget-agent-mcp", "--modules", "account,trade,market,cryptoloans,tax"] }

CLI 选项和环境变量

bitget-agent-mcp [options]

  --modules <list>     account, trade, market, strategy,
                       cryptoloans, tax
                       "all" loads every module.
                       Default: account,trade,market

  --surface <mode>     intent  curated verbs + discover + raw (default)
                       full    ALSO emit one tool per underlying v3 endpoint

  --read-only          Expose only read/query operations; block all writes.
  --paper-trading      Enable Demo Trading mode (requires a Demo API Key).
                       Mutually exclusive with --read-only.
  --help               Show help and exit
  --version            Show version and exit

变量	用途
BITGET_API_KEY	私有端点所必需
BITGET_SECRET_KEY	私有端点所必需
BITGET_PASSPHRASE	私有端点所必需
BITGET_API_BASE_URL	可选的 API 基础 URL（默认值为 https://api.bitget.com）
BITGET_TIMEOUT_MS	可选的请求超时时间，单位为 ms（默认值为 15000）
BITGET_MAX_RETRIES	可选的最大传输重试次数（默认值：SDK 策略）

没有 API 凭据时，只有公开/读取（市场数据）操作可以成功。

模块和意图动词

默认配置文件会加载 account,trade,market。完整配置包含 6 个模块和 14 个精选意图动词：

模块	默认启用	意图动词	操作数
market	✅	market	16
trade	✅	order、position、strategy_order	17
account	✅	account_overview、account_config、repayment、transfer_funds、deposit、withdraw、funds_records、subaccount	39
strategy	按需	扩展 strategy_order（计划单 / TP-SL 订单）	5
cryptoloans	按需	loan	11
tax	按需	tax	1

无论使用哪个模块，始终都会提供：discover（自省）和 raw（通过 operationId 访问任何 v3 操作）。

---

安全

凭证保护

• ✅ 绝不会离开你的设备 — API 密钥仅从环境变量中读取，绝不会被记录到日志、写入磁盘或通过任何服务代理。
• ✅ 本地签名 — 所有经过身份验证的请求都会在进程内通过 HMAC-SHA256 签名，然后直接连接到 Bitget 官方 API。
• ✅ 通过 stdio 在本地运行 — 不会监听网络，没有需要加固的远程端点，也不会收集遥测数据。

安全模式

• --read-only — 在整个会话期间阻止所有写入操作；AI 可以查询，但不能下单、转账、取消或提现。
• --paper-trading — 将已签名的请求发送到 Bitget 的 Demo 环境。不涉及真实资金。需要单独的 Demo API Key。
• 写入安全门 — 高风险或不可逆操作必须明确设置 confirm: true，所有写入操作均支持使用 dryRun: true 进行无网络预览。

速率限制

SDK 会应用客户端重试／速率限制策略，防止 AI 循环向 Bitget API 发送过多请求。如果 Bitget 返回 429，SDK 会自动退避并重试。

---

故障排除

“Command not found: npx”

原因： 未安装 Node.js，或 Node.js 不在 PATH 中。 解决方法： 从 nodejs.org 安装 Node.js ≥ 20，然后重启终端／宿主程序。

“Authentication failed” 或 “Invalid API key”

可能原因和解决方法：

1. API 密钥缺少权限 → 在 API Management 中启用 Read + Trade。
2. Passphrase 错误 → 按照显示内容准确复制全部三个值。
3. 在 --paper-trading 模式下使用了实盘密钥（或反之） → 模拟交易请使用 Demo API Key。

“Tool not recognized by AI”

原因： MCP 服务配置不正确，或未重启宿主程序。 解决方法： 确认配置文件是有效的 JSON，完全重启宿主程序，然后询问 “列出可用的 MCP 工具。”

Cursor 显示的 Bitget 工具少于预期

原因： 其他 MCP 服务占用了 Cursor 的 40 个工具上限。Bitget 默认配置包含 14 个工具。 解决方法： 移除未使用的 MCP 服务，或使用 --modules 仅加载所需内容。

“Rate limit exceeded”

原因： 调用过于频繁。 解决方法： SDK 会自动限流，但如果触发 Bitget 服务端限制，请等待约 60 秒后再重试。避免要求 AI 连续快速下达数百笔订单。

MCP 服务无法启动

检查： Node.js 版本（node --version ≥ 20）、是否能够访问网络地址 api.bitget.com，以及出站 HTTPS 是否被防火墙阻止。

---

更新

由于安装使用 npx -y，每次 AI 宿主程序启动时都会自动获取最新版本——无需手动更新。

如需强制刷新 npm 缓存：

npx @bitget-ai/bitget-agent-mcp@latest --version

如需一次性升级整个 Bitget AI 工具包，请使用 agent_hub 中的安装程序。

---

相关项目

Package	Purpose	Best for
agent-cli	终端 AI 交易工具（bgc）	Claude Code、Codex CLI、原生 Shell Agent
agent-skill	CLI 的 AI 推理指南	教 Agent 正确使用 bgc
agent-sdk	TypeScript 基础 SDK	构建自定义集成的开发者
bitget-signal	市场分析技能（无需 API 密钥）	宏观、链上、情绪、技术分析、新闻
agent_hub	生态系统中心入口 + 安装程序	了解所有 Bitget AI 工具

---

常见问题

bitget-agent-mcp 是什么？

它是 Bitget 的官方 MCP（Model Context Protocol）服务。它通过 MCP 标准，向桌面 AI 客户端（Claude Desktop、Cursor、Windsurf、ChatGPT Desktop、……）提供 89 项 Bitget UTA v3 操作，包括 14 个精选意图动词、一个 discover 自省工具和一个 raw 备用入口。

这与 agent-cli 有什么不同？

• bitget-agent-mcp — 面向使用 MCP 的桌面 AI 宿主（Claude Desktop、Cursor 等）。
• agent-cli（bgc）— 面向终端 AI（Claude Code、Codex CLI），可在你的 Shell 中运行命令。

两者基于相同的 SDK，并提供相同的意图接口——选择与你的 AI 工具相匹配的版本。

为什么使用意图动词，而不是每个端点对应一个工具？

每个端点对应一个工具的服务会为每个端点提供一个工具，导致模型上下文臃肿，并降低工具选择的准确性。意图接口将默认工具列表控制在 14 个工具（12 个动词 + discover + raw），同时仍能直接覆盖全部 89 个默认暴露的操作；需要访问较少用到的操作时，raw 可通过 operationId 调用任何操作。Agent 只会在需要时使用 discover 深入了解详情。

默认加载哪些模块？

默认加载：account（39 个操作）、trade（17 个操作）、market（16 个操作）= 72 个操作，通过 12 个意图动词以及 discover 和 raw 暴露（总计 14 个工具）。使用 --modules strategy,cryptoloans,tax 或 --modules all 加载更多模块（可通过 14 个动词访问 89 个端点）。

Cursor 有工具数量限制吗？

有——Cursor 将 MCP 工具总数限制为 40 个。默认 Bitget 配置加载 14 个工具，远低于上限（还剩 26 个名额）。--modules all 会加载 16 个工具。

如何防止意外下单？

在配置参数中添加 "--read-only"。会话中的所有写入操作都会被拒绝——AI 可以查询余额和市场信息，但无法下单、转账、取消订单或提现。

我可以在不冒真实资金风险的情况下测试吗？

可以——使用模拟交易：创建一个 Demo API Key，将 Demo 凭证设为环境变量，并在参数中添加 "--paper-trading"。签名请求会发送到 Bitget 的 Demo 环境。

我的 API 密钥安全吗？

安全。凭证仅保存在宿主的 MCP 配置中，不会经由任何服务转发；请求到达 Bitget 前会在本地使用 HMAC-SHA256 签名；此服务绝不会记录凭证或将其写入磁盘。

这是免费的吗？

是——采用 MIT 许可证，个人和商业用途均免费。Bitget 免费维护此 MCP 服务。

支持哪些 AI 工具？

Claude Desktop、Cursor、Continue、ChatGPT Desktop、Windsurf，以及任何通过 stdio 传输进行通信的 MCP 客户端。

---

参与贡献

欢迎提交问题和拉取请求。

• 报告 Bug / 请求功能：GitHub Issues
• **安全问题：**请通过 repository 的 GitHub 安全公告功能私下报告——不要公开创建 Issue。

---

许可证

MIT License — 个人和商业用途均免费。

---

_{⚠️ 风险免责声明：加密货币交易风险极高。对于 AI Agent 代表你下达的任何订单，你须自行承担全部责任。请使用 --read-only 和 --paper-trading 安全演练后再进行真实交易。过往表现不代表未来结果。}

_{Bitget Agent Hub 官方工具 · 属于 Bitget 开源 AI 生态系统 · 基础项目：agent-sdk · 其他工具：agent-cli · agent-skill · 市场信号：bitget-signal}