Gainium
OfficialThis MCP server lets AI assistants interact with Gainium’s crypto trading bot platform to inspect and manage bots, deals, backtests, account data, market data, and presets.
List and inspect DCA, Combo, and Grid bots, with filtering, pagination, paper/real context, and field selection.
Create, update, clone, and manage bot lifecycle actions such as start, stop, archive, restore, and change trading pairs.
List, inspect, create, update, and manage deals, including closing deals and adding or reducing funds.
Run backtests in validate, estimate, async, or sync modes, and list or fetch backtest requests.
Discover bot schemas, bot sections, indicators, and supported exchanges.
Retrieve account balances, connected exchanges, global variables, and supported exchanges.
Query the crypto screener with market filters and client-side sorting.
Create, update, and delete global variables.
List curated strategy presets ranked by backtested performance and create bots from presets.
Use efficient field-selection presets such as minimal, standard, extended, and full.
gainium-mcp
An MCP (Model Context Protocol) server for Gainium — the crypto trading bot platform. Lets AI assistants manage your bots, deals, balances, and more through a standard MCP interface.
Detailed setup and connection documentation is available in docs/using-gainium-mcp.md.
Quick Start
1. Get your API keys
Go to Gainium API Settings and create an API key pair.
2. Add to your MCP client
Add this to your MCP configuration (VS Code, Claude Desktop, etc.):
{
"gainium-mcp": {
"command": "npx",
"args": ["-y", "gainium-mcp"],
"env": {
"GAINIUM_API_KEY": "<your-api-key>",
"GAINIUM_API_SECRET": "<your-api-secret>"
}
}
}That's it. The server starts automatically when your AI assistant needs it.
This local stdio mode uses GAINIUM_API_KEY and GAINIUM_API_SECRET from the server process environment.
Environment Variables
Variable | Required | Default | Description |
| Yes | — | Your Gainium API public key |
| Yes | — | Your Gainium API secret |
| No |
| API base URL |
| No |
| Transport mode: |
| No |
| Bind host for HTTP mode |
| No |
| Bind port for HTTP mode |
| No | — | Comma-separated hostnames (optionally |
| No |
| Streamable HTTP endpoint path |
| No |
| Deprecated SSE GET endpoint path |
| No |
| Deprecated SSE POST endpoint path |
| No | — | Authorization-server base URL. Setting this (with |
| No |
| Token introspection endpoint |
| No | — | Shared secret presented to the introspection endpoint (must match the auth server) |
| No | derived from request | Public base URL used in the protected-resource metadata |
| No | — | When set, served as plain text at |
Related MCP server: freqtrade-mcp-server
Authentication Modes
gainium-mcp supports three deployment models:
Local stdio mode: the MCP server reads
GAINIUM_API_KEYandGAINIUM_API_SECRETfrom env vars.OAuth 2.1 hosted mode (recommended for hosted/public): the server acts as an OAuth protected resource. Clients (e.g. the Claude connector) obtain an access token from the Gainium authorization server and send it as
Authorization: Bearer <token>. See OAuth 2.1 hosted mode below.Header hosted mode (legacy/self-hosted): each request sends
X-API-KeyandX-API-Secretheaders so one shared server can serve many users.
In header/stdio mode, request headers take priority, falling back to GAINIUM_API_KEY / GAINIUM_API_SECRET. When OAuth mode is enabled, the Bearer token is required and the X-API-Key/X-API-Secret headers are ignored.
OAuth 2.1 hosted mode
This is the mode used for the public https://mcp.gainium.io/mcp endpoint and the Anthropic Claude connector directory (which requires OAuth and forbids API-key headers).
Enable it by setting, in HTTP mode:
export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_OAUTH_ISSUER=https://app.gainium.io # Gainium authorization server
export MCP_INTROSPECTION_SECRET=<shared-secret> # must match the auth server
export GAINIUM_MCP_PUBLIC_URL=https://mcp.gainium.io # this server's public URL
# optional, defaults to <issuer>/oauth/introspect:
# export GAINIUM_INTROSPECTION_URL=https://app.gainium.io/oauth/introspect
node dist/server.jsWhen enabled, the server:
Serves OAuth Protected Resource Metadata (RFC 9728) at
/.well-known/oauth-protected-resourceand/.well-known/oauth-protected-resource/mcp, advertising the authorization server.Rejects unauthenticated MCP requests with
401 Unauthorizedand aWWW-Authenticate: Bearer resource_metadata="…"header, so clients can discover the auth server and run the OAuth flow (Dynamic Client Registration + PKCE).Validates the Bearer access token on each request via the auth server's token introspection endpoint, resolving it to the user's Gainium
(apiKey, apiSecret)and per-key restrictions (read/write, paper-only, single-bot), which are still enforced server-side. Introspection results are cached briefly.
The local stdio path is unaffected by these variables.
HTTP and SSE Mode
By default, gainium-mcp runs over stdio for MCP clients that spawn local processes. To run it as an HTTP server instead:
export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_MCP_HOST=127.0.0.1
export GAINIUM_MCP_PORT=3000
node dist/server.jsWhen HTTP mode is enabled, the server exposes both transport styles:
GET|POST|DELETE /mcpfor the current Streamable HTTP transportGET /sseplusPOST /messages?sessionId=...for deprecated HTTP+SSE clients
This makes one server process compatible with both modern MCP HTTP clients and older SSE-based integrations. In hosted mode, authenticate with OAuth (see OAuth 2.1 hosted mode) or, for self-hosted/legacy setups, send X-API-Key and X-API-Secret on each request.
Available Tools (17)
As of v3.0.0 the toolset is consolidated: a single tool per operation, with a
botType / dealType / action discriminator instead of one tool per variant.
Every tool carries an MCP safety annotation — read-only tools set readOnlyHint,
write tools set destructiveHint.
Bots
Tool | Access | Description |
| read | List bots by type ( |
| read | Get a single bot by id and type |
| write | Create a bot ( |
| write | Update bot settings |
| write | Clone a bot with optional overrides |
| write | Lifecycle action: |
Deals
Tool | Access | Description |
| read | List deals by type ( |
| read | Get a single deal by id and type |
| write | Create a deal |
| write | Update an active deal |
| write | Deal action: |
Backtest
Tool | Access | Description |
| write | Run a backtest: |
| read | List backtest requests or get one by ID |
Discovery, Account & Market
Tool | Access | Description |
| read | Schema discovery for bot types and indicators |
| read | Balances, connected exchanges, supported exchanges, and global variables |
| read | Cryptocurrency screener with market metrics |
| write | Global variable action: |
Field Selection
All GET endpoints support the fields parameter for efficient payloads:
Presets:
minimal,standard(default),extended,fullCustom: comma-separated dot-notation fields (e.g.
_id,uuid,settings.name,profit.total)
Using minimal reduces payload size by ~85%.
API Permissions
Read-only key: read tools only (
list_*,get_*,discover,backtest_info,get_screener,list_presets)Write key: all tools, including
create_*,update_*,clone_bot,manage_bot,manage_deal,manage_global_variable,apply_preset, andrun_backtestRead-only directory connector (
/mcpwithGAINIUM_READONLY=true, served atmcp.gainium.io/read): exposes and allows only the 9readOnlyHinttools —run_backtestand all write tools are excludedToken audience binding (OAuth mode): when
GAINIUM_MCP_PUBLIC_URLis set, the server treats<public-url><http-path>as its RFC 8707 resource. An access token whose introspectedaudis a different resource is rejected — a token minted formcp.gainium.io/readcan't be replayed againstmcp.gainium.io/mcp, and vice versa. Tokens with noaud(legacy grants) are still accepted.
Development
# Clone and install
git clone https://github.com/gainium/gainium-mcp.git
cd gainium-mcp
npm install
# Build
npm run build
# Run locally (for testing)
export GAINIUM_API_KEY=your_key
export GAINIUM_API_SECRET=your_secret
node dist/server.js
# Run in HTTP/SSE mode
export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_MCP_PORT=3000
node dist/server.jsArchitecture
gainium-mcp/
├── src/
│ ├── server.ts # MCP server + tool definitions (stdio + HTTP/SSE transports)
│ └── gainium-client.ts # HMAC-authenticated HTTP client for Gainium API v2
├── dist/ # Compiled output (published to npm)
├── package.json
├── tsconfig.json
└── README.mdLicense
MIT
Available Tools
19 toolsapply_presetADestructiveInspect
Create a bot from a curated preset in one call: fetches the preset for the given coin/exchange/tier/strategy, then creates a bot from its settings. Override pair, name, or sizing as needed.
Inputs: botType (required), coin (required), exchange (required), tier (required), +5 more.
backtest_infoARead-onlyInspect
Get backtest information: list requests, fetch a specific request, get operation schema, or build a payload template.
Inputs: target (required), botType (required), fields, page, +2 more. Returns: For target="requests"/"request": the Gainium API envelope ({status, reason, dat…
clone_botADestructiveInspect
Clone an existing bot and optionally override settings. Returns the new bot ID.
Inputs: botType (required), botId (required), paperContext, overrides.
create_botADestructiveInspect
Create a new bot in a single step — no follow-up update needed. The top-level properties cover the most common fields. For any field from discover(target: "bot") that is NOT listed here (e.g. startOrderType, useMoveTP, moveTPTrigger, moveTPValue, stopLossTimeout, takeProfitTimeout, dcaOrdersMultiplier, dcaStepMultiplier, trailingTP, trailingTPPerc, indicators, timers, and any other discovery field), pass them inside the 'settings' object — it is transparently merged into the request body at creation time. This avoids a create→update two-step. Use discover(target: 'bot', botType) to discover all available fields and defaults. The 'futures' and 'coinm' fields are auto-detected from the exchange — do not provide them. Requires write API key permission.
Inputs: botType (required), exchangeUUID (required), pair (required), paperContext, +24 more.
create_dealADestructiveInspect
Create a new deal. For dca/combo: starts a deal from an existing bot. For terminal: creates a standalone terminal deal.
Inputs: dealType (required), paperContext, botId, symbol, +9 more.
discoverARead-onlyInspect
Discover bots, bot details, bot sections, indicators, or supported exchanges. Use this to learn available fields, defaults, and strategies.
Inputs: target (required), botType, section, type, +2 more. Returns: Gainium API envelope with discovery metadata in `data`.
get_accountBRead-onlyInspect
Get account information: balances, connected exchanges, global variables, or supported exchanges.
Inputs: info (required), fields, page, paperContext, +3 more. Returns: Gainium API envelope with account information in `data`.
get_botARead-onlyInspect
Get a single bot by its MongoDB ObjectId or UUID. Supports the same field selection presets as list_bots.
Inputs: botType (required), botId (required), fields, paperContext. Returns: Gainium API envelope with the bot in `data`.
get_dealARead-onlyInspect
Get a single deal by its MongoDB ObjectId. Supports the same field selection presets as list_deals.
Inputs: dealType (required), dealId (required), fields, paperContext. Returns: Gainium API envelope with the deal in `data`.
get_screenerCRead-onlyInspect
Get cryptocurrency screener results. Filter by market cap, volume, and sort by various metrics.
Inputs: fields, page, category, minMarketCap, +5 more. Returns: Gainium API envelope with screener rows in `data`.
list_botsARead-onlyInspect
List bots by type (DCA, Combo, or Grid). Supports field selection presets (minimal, standard, extended, full). Supports filtering by status and paper/real trading context.
Inputs: botType (required), fields, page, status, +1 more. Returns: Gainium API envelope with the list of bots in `data`.
list_dealsARead-onlyInspect
List deals by type (DCA, Combo, or Terminal). Supports field selection presets. Supports filtering by status and botId.
Inputs: dealType (required), fields, page, status, +2 more. Returns: Gainium API envelope with the list of deals in `data`.
list_presetsARead-onlyInspect
List curated bot-strategy presets, ranked by backtested performance. Each coin returns tiers (short/mid/long) × strategy (long/short) with ROI, drawdown, and the full strategy settings for review and comparison.
Inputs: botType (required), coin, exchange, strategy, +3 more. Returns: Gainium API envelope with curated presets in `data`.
manage_botADestructiveInspect
Manage bot lifecycle: start, stop, archive, restore, or change trading pairs (DCA only). Each action has specific requirements.
Inputs: action (required), botId (required), botType (required), paperContext, +4 more.
manage_dealBDestructiveInspect
Manage deal operations: close a deal, add funds, or reduce funds. Each action has specific requirements.
Inputs: action (required), dealId (required), dealType (required), paperContext, +6 more.
manage_global_variableADestructiveInspect
Create, update, or delete a global variable. Variables are user-defined constants accessible in strategies.
Inputs: action (required), id, name, type, +1 more.
run_backtestAInspect
Run a backtest operation: validate, estimate cost, request async, or request with sync response. Pass a backtest payload with exchange, exchangeUUID, and bot settings.
Inputs: mode (required), botType (required), payload (required), paperContext, +1 more.
update_botADestructiveInspect
Update an existing bot (DCA or Combo only; Grid has no update endpoint). Pass only the fields you want to change. Settings object must be non-empty. Boolean gate enforcement: feature value fields are silently ignored unless their toggle is set to true.
Inputs: botType (required), botId (required), settings (required), paperContext.
update_dealADestructiveInspect
Update an existing deal. Pass only the fields you want to change. Settings object must be non-empty.
Inputs: dealType (required), dealId (required), settings (required), paperContext.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool has a clearly distinct purpose, covering bots, deals, backtesting, presets, account, screener, and global variables. No two tools overlap in functionality.
Most tools follow verb_noun snake_case (e.g., create_bot, list_deals). Only 'discover' (verb only) and 'backtest_info' (noun_noun) deviate, making the set mostly consistent but not perfect.
19 tools is slightly above the typical 3-15 range, but each tool covers a necessary aspect of a trading bot platform. The count is justified by the breadth of functionality.
The tool set covers core operations for bots and deals, but lacks delete operations and management of exchanges or presets. Notable gaps exist that agents would need to work around.
Maintenance
Related MCP Connectors
Create and manage trading strategies, bots, webhooks and signals from any MCP client.
Trade 16 crypto exchanges + MetaTrader 5 from your AI assistant via one MCP connection.
Unofficial Market Data App MCP — wraps the Market Data App API (marketdata.app)
Remote MCP server for crypto trading signals and the public ledger that scores them, losses included. Read tools: open signals, the signal ledger (matured wins and losses), signals cancelled by the BTC regime veto with the outcome they would have had, market snapshot and ticker for scanned Binance symbols, the scheduled BTC chart read, and news headlines. The public read tools work without a key. With a free API key from ribqa.com: your own bots and strategies, and rate-limited strategy backtests. No tool places, simulates or cancels an order. Free during beta.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for Binance USDT-M Futures trading — exposes tools for market data, account state, order management, and position/margin control.238Apache 2.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server for cryptocurrency trading via Freqtrade, enabling trade management, balance checks, strategy configuration, backtesting, and bot lifecycle control from any MCP-compatible AI agent.MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI tools to execute trades and fetch market data across six crypto exchanges via natural language or API, with dual Telegram and MCP interfaces.2-
- AlicenseBqualityDmaintenanceEnables AI agents to trade crypto with paper money, access market data, view leaderboards, and manage trading bots via an MCP-compatible interface.16MIT