bitget-agent-mcp — Official Bitget MCP Trading Server

Connect Claude Desktop, Cursor, Continue, Windsurf & ChatGPT to Bitget via the Model Context Protocol — trade crypto with natural language.

Quick Start · Capabilities · How It Works · Installation · Configuration · Security · Troubleshooting · FAQ

---

Overview

bitget-agent-mcp is the official Model Context Protocol (MCP) server for Bitget, enabling desktop AI agents like Claude Desktop, Cursor, Continue, Windsurf, and ChatGPT Desktop to operate your Bitget account through natural-language commands.

It is built on the Bitget Unified Trading Account (UTA / v3) API and covers 89 trading operations across market data, spot, futures, account & funds management, sub-accounts, loans, and tax. Crucially, it does not flood your model with one tool per endpoint. Instead it exposes a small, progressively-discoverable intent surface of 14 curated intent verbs (the default profile loads 12 verbs + discover + raw = 14 tools) so AI hosts get full capability without the context bloat and tool-selection errors that plague endpoint-per-tool servers.

Part of Bitget Agent Hub — the official open-source AI ecosystem for Bitget, including the CLI, SDK, installer, and market-analysis skills.

---

Quick Start

Prerequisites

• Node.js ≥ 20 (download)
• Bitget API Key (create here) — enable Read + Trade permissions
• An MCP-capable AI host (Claude Desktop, Cursor, Continue, Windsurf, ChatGPT Desktop, or any stdio MCP client)

One-Step Install (Recommended)

Paste this prompt into your AI agent (Claude Desktop / Cursor / etc.):

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.

The agent will detect your tool, add the npx server entry, wire up credentials, and verify the connection.

Manual Install

Prefer to edit config files yourself? Jump to Configuration for per-tool JSON snippets. The command is always:

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

---

What You Can Do

Once configured, your AI gains native access to Bitget's trading stack through natural language. A few examples (every one maps to a real operation in the surface):

Ask your AI	What happens	Credentials
"What's the current BTC price?"	Live ticker via the market verb	❌ No
"Pull the 4h BTC candles"	OHLCV / K-line history via market	❌ No
"What's the BTC perp funding rate?"	Funding rate via market	❌ No
"Show my USDT balance across accounts"	Account overview via account_overview	✅ Yes
"Buy 0.1 BTC at market"	Spot market order via order	✅ Yes
"Set leverage to 10x and open a BTC long"	account_config + order / position	✅ Yes
"List my open orders"	order (open)	✅ Yes
"Transfer 500 USDT from spot to futures"	Internal transfer via transfer_funds	✅ Yes
"Cancel all my open orders"	order (cancelAll) — high-risk, asks to confirm	✅ Yes
"Borrow USDT against my collateral"	Crypto loan via loan	✅ Yes

Market data (the market verb) is public and works without API credentials; everything that touches your account requires keys.

Advanced Modes

• --read-only — Blocks every write operation for the session. The verbs stay visible, but any order, transfer, cancellation, or withdrawal is rejected before it reaches Bitget. Ideal for safe exploration. (Mutually exclusive with --paper-trading.)
• --paper-trading — Routes signed requests to Bitget's Demo Trading environment (adds the paptrading: 1 header). Requires a separate Demo API Key. Perfect for rehearsing strategies risk-free.
• --modules <list> — Load only the modules you need. Default: account,trade,market. On-demand: strategy, cryptoloans, tax.
• --surface <intent|full> — intent (default) exposes the curated verbs. full additionally emits one tool per underlying v3 endpoint.

---

How an Agent Uses It

The intent surface is progressively discoverable. Rather than reading every schema up front, the agent follows discover → drill down → execute:

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

If the prompt already implies the verb and arguments, the agent skips discovery and calls directly. discover({ search: "funding" }) keyword-searches the whole surface when the domain is unknown. The two meta-tools are always present:

• discover — progressive introspection of the surface.
• raw — an escape hatch that reaches any v3 operation by operationId for the long tail. (In practice every operation is also covered by a verb, so raw is rarely needed.)

Write Safety

• Ordinary writes execute immediately.
• High-risk / irreversible operations (e.g. cancelAll, withdraw) return { confirmationRequired: true } unless you pass confirm: true.
• Any write accepts dryRun: true to preview the would-send request without sending it.

MCP tool annotations are derived from the SDK's riskLevel (read / write / high), so hosts can flag destructive operations before the model invokes them.

---

Architecture

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

How it works:

1. Your AI host launches the MCP server locally via npx over stdio — no network listener, no proxy.
2. Credentials are passed as environment variables from your host's config; the server never stores, logs, or proxies them.
3. All authenticated requests are signed in-process with HMAC-SHA256 and sent directly to Bitget's official API.
4. Responses flow back through MCP to your AI conversation.

All the "smarts" — discovery, intent routing, the write-safety gate, signing, and response shaping — live in @bitget-ai/bitget-agent-sdk. This package is a thin stdio adapter on top of it.

---

Installation

Supported AI Hosts

AI Host	Status	Notes
Claude Desktop	✅	First-class, via claude_desktop_config.json
Cursor	✅	Default profile fits the 40-tool cap with room to spare
Continue	✅	VS Code / JetBrains extension
ChatGPT Desktop	✅	OpenAI's desktop client
Windsurf	✅	Codeium's AI IDE
Any MCP client	✅	Anything that speaks MCP over stdio

Step-by-Step Setup

1. Get Your API Key

1. Log in to bitget.com
2. Go to Profile → API Management
3. Click Create API Key
4. Enable Read and Trade permissions
5. Copy the three values: API Key, Secret Key, Passphrase

⚠️ Security note: store these securely. Never share them or commit them to version control.

2. Configure your host

Use the one-step prompt, or add the server to your host's MCP config manually (see Configuration).

3. Verify

Ask your AI: "What Bitget tools are available?" You should see verbs like market, order, position, account_overview, plus discover and raw.

---

Configuration

Claude Desktop

Edit 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"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Settings → MCP → Add New Server:

Field	Value
Command	npx
Args	-y @bitget-ai/bitget-agent-mcp
Env	BITGET_API_KEY, BITGET_SECRET_KEY, BITGET_PASSPHRASE

⚠️ Cursor tool limit: Cursor caps total MCP tools at 40 across all servers. The default Bitget profile loads 14 tools (12 intent verbs + discover + raw), leaving 26 slots for other servers. --modules all yields 16 tools.

Continue / Windsurf / ChatGPT Desktop / other MCP hosts

Use the same npx -y @bitget-ai/bitget-agent-mcp command and pass credentials via environment variables, following your tool's MCP configuration docs. If the host speaks MCP over stdio, it works.

Custom Configuration Examples

Read-only mode (safe for exploration):

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

Paper trading (Demo environment — use Demo API keys):

{
  "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"
  }
}

Load extra modules:

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

CLI Options & Environment Variables

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

Variable	Purpose
BITGET_API_KEY	Required for private endpoints
BITGET_SECRET_KEY	Required for private endpoints
BITGET_PASSPHRASE	Required for private endpoints
BITGET_API_BASE_URL	Optional API base URL (default https://api.bitget.com)
BITGET_TIMEOUT_MS	Optional request timeout in ms (default 15000)
BITGET_MAX_RETRIES	Optional max transport retries (default: SDK policy)

Without API credentials, only public/read (market data) operations succeed.

Modules & Intent Verbs

The default profile loads account,trade,market. The full set spans 6 modules and 14 curated intent verbs:

Module	Default	Intent verbs	Operations
market	✅	market	16
trade	✅	order, position, strategy_order	17
account	✅	account_overview, account_config, repayment, transfer_funds, deposit, withdraw, funds_records, subaccount	39
strategy	on-demand	extends strategy_order (plan / TP-SL orders)	5
cryptoloans	on-demand	loan	11
tax	on-demand	tax	1

Always present regardless of module: discover (introspection) and raw (reach any v3 operation by operationId).

---

Security

Credential Protection

• ✅ Never leaves your machine — API keys are read from environment variables only, never logged, written to disk, or proxied through any server.
• ✅ Local signing — all authenticated requests are signed in-process with HMAC-SHA256 before connecting directly to Bitget's official API.
• ✅ Runs locally over stdio — no network listener, no remote endpoint to harden, no telemetry.

Safety Modes

• --read-only — blocks all write operations for the session; the AI can query but cannot place orders, transfer funds, cancel, or withdraw.
• --paper-trading — routes signed requests to Bitget's Demo environment. No real funds involved. Requires a separate Demo API Key.
• Write-safety gate — high-risk/irreversible operations require an explicit confirm: true, and any write supports dryRun: true for a no-network preview.

Rate Limiting

The SDK applies a client-side retry/rate-limit policy that protects against AI loops hammering Bitget's API. If Bitget returns a 429, it backs off and retries automatically.

---

Troubleshooting

"Command not found: npx"

Cause: Node.js not installed or not on PATH. Fix: install Node.js ≥ 20 from nodejs.org and restart your terminal/host.

"Authentication failed" or "Invalid API key"

Likely causes & fixes:

1. API key lacks permissions → enable Read + Trade at API Management.
2. Passphrase is wrong → copy all three values exactly as shown.
3. Live keys used with --paper-trading (or vice versa) → use a Demo API Key for paper trading.

"Tool not recognized by AI"

Cause: MCP server not configured correctly, or the host wasn't restarted. Fix: validate the config file is valid JSON, restart the host completely, then ask "List available MCP tools."

Cursor shows fewer Bitget tools than expected

Cause: other MCP servers consuming Cursor's 40-tool cap. The Bitget default profile is 14 tools. Fix: remove unused MCP servers, or use --modules to load only what you need.

"Rate limit exceeded"

Cause: too many rapid calls. Fix: the SDK auto-throttles, but if you hit Bitget's server-side limit, wait ~60s before retrying. Avoid asking the AI to place hundreds of orders in quick succession.

MCP server won't start

Check: Node.js version (node --version ≥ 20), network reachability to api.bitget.com, and that outbound HTTPS isn't blocked by a firewall.

---

Updates

Because installation uses npx -y, the latest version is pulled automatically each time your AI host starts — no manual updates needed.

To force-refresh the npm cache:

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

To upgrade the whole Bitget AI toolkit at once, use the installer in agent_hub.

---

Related Projects

Package	Purpose	Best for
agent-cli	Terminal AI trading tool (bgc)	Claude Code, Codex CLI, shell-native agents
agent-skill	AI reasoning guide for the CLI	Teaching agents how to use bgc correctly
agent-sdk	TypeScript foundation SDK	Developers building custom integrations
bitget-signal	Market-analysis skills (no API key)	Macro, on-chain, sentiment, technical, news
agent_hub	Central ecosystem entry + installer	Overview of all Bitget AI tools

---

FAQ

What is bitget-agent-mcp?

It's the official MCP (Model Context Protocol) server for Bitget. It exposes 89 Bitget UTA v3 operations to desktop AI clients (Claude Desktop, Cursor, Windsurf, ChatGPT Desktop, …) through 14 curated intent verbs plus a discover introspection tool and a raw escape hatch — over the MCP standard.

How is this different from agent-cli?

• bitget-agent-mcp — for desktop AI hosts that speak MCP (Claude Desktop, Cursor, …).
• agent-cli (bgc) — for terminal AI (Claude Code, Codex CLI) that runs commands in your shell.

Both sit on the same SDK and expose the same intent surface — pick the one that matches your AI tool.

Why intent verbs instead of one tool per endpoint?

Endpoint-per-tool servers advertise one tool per endpoint, which bloats the model's context and degrades tool-selection accuracy. The intent surface keeps the default tool list at 14 tools (12 verbs + discover + raw) while still covering all 89 default-exposed operations directly — and raw reaches any operation by operationId when you need the long tail. The agent uses discover to drill into detail only when it needs to.

Which modules are loaded by default?

Default: account (39 ops), trade (17 ops), market (16 ops) = 72 operations, exposed through 12 intent verbs plus discover and raw (14 tools total). Load more with --modules strategy,cryptoloans,tax or --modules all (which reaches the 14 verbs across 89 endpoints).

Does Cursor have a tool limit?

Yes — Cursor caps total MCP tools at 40. The default Bitget profile loads 14 tools, well within the cap (26 slots free). --modules all yields 16 tools.

How do I prevent accidental orders?

Add "--read-only" to your config args. Every write operation is rejected for the session — the AI can query balances and markets but cannot place orders, transfer funds, cancel, or withdraw.

Can I test without risking real funds?

Yes — use paper trading: create a Demo API Key, set the Demo credentials as environment variables, and add "--paper-trading" to your args. Signed requests route to Bitget's Demo environment.

Is my API key safe?

Yes. Credentials live only in your host's MCP config, are never proxied through any server, are signed locally with HMAC-SHA256 before reaching Bitget, and are never logged or written to disk by this server.

Is it free?

Yes — MIT-licensed and free for personal and commercial use. The MCP server is maintained by Bitget at no cost.

What AI tools are supported?

Claude Desktop, Cursor, Continue, ChatGPT Desktop, Windsurf, and any MCP client that communicates over stdio transport.

---

Contributing

Issues and pull requests are welcome.

• Report bugs / request features: GitHub Issues
• Security issues: please report privately via GitHub's security advisory feature on the repository — do not open a public issue.

---

License

MIT License — free for personal and commercial use.

---

_{⚠️ Risk disclaimer: trading cryptocurrency carries substantial risk. You are solely responsible for any orders your AI agent places on your behalf. Use --read-only and --paper-trading to rehearse safely before going live. Past performance does not guarantee future results.}

_{Official Bitget Agent Hub tool · Part of the Bitget open-source AI ecosystem · Foundation: agent-sdk · Other surfaces: agent-cli · agent-skill · Market signals: bitget-signal}