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):

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

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

Read the full README on GitHub →