Skip to main content
Glama
Gainium

Gainium

Official
by Gainium

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

GAINIUM_API_KEY

Yes

—

Your Gainium API public key

GAINIUM_API_SECRET

Yes

—

Your Gainium API secret

GAINIUM_API_BASE_URL

No

https://api.gainium.io

API base URL

GAINIUM_MCP_TRANSPORT

No

stdio

Transport mode: stdio, http, streamable-http, sse, or http-sse

GAINIUM_MCP_HOST

No

127.0.0.1

Bind host for HTTP mode

GAINIUM_MCP_PORT

No

3000

Bind port for HTTP mode

GAINIUM_MCP_ALLOWED_HOSTS

No

—

Comma-separated hostnames (optionally host:port) accepted in the Host/Origin headers. In HTTP mode with env credentials and no OAuth, only loopback, IP-literal and these hosts are served (DNS rebinding protection)

GAINIUM_MCP_HTTP_PATH

No

/mcp

Streamable HTTP endpoint path

GAINIUM_MCP_SSE_PATH

No

/sse

Deprecated SSE GET endpoint path

GAINIUM_MCP_MESSAGES_PATH

No

/messages

Deprecated SSE POST endpoint path

GAINIUM_OAUTH_ISSUER

No

—

Authorization-server base URL. Setting this (with MCP_INTROSPECTION_SECRET, in HTTP mode) enables OAuth protected-resource mode

GAINIUM_INTROSPECTION_URL

No

<issuer>/oauth/introspect

Token introspection endpoint

MCP_INTROSPECTION_SECRET

No

—

Shared secret presented to the introspection endpoint (must match the auth server)

GAINIUM_MCP_PUBLIC_URL

No

derived from request

Public base URL used in the protected-resource metadata

OPENAI_APPS_CHALLENGE_TOKEN

No

—

When set, served as plain text at /.well-known/openai-apps-challenge for OpenAI Apps domain verification

Related MCP server: freqtrade-mcp-server

Authentication Modes

gainium-mcp supports three deployment models:

  • Local stdio mode: the MCP server reads GAINIUM_API_KEY and GAINIUM_API_SECRET from 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-Key and X-API-Secret headers 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.js

When enabled, the server:

  1. Serves OAuth Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp, advertising the authorization server.

  2. Rejects unauthenticated MCP requests with 401 Unauthorized and a WWW-Authenticate: Bearer resource_metadata="…" header, so clients can discover the auth server and run the OAuth flow (Dynamic Client Registration + PKCE).

  3. 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.js

When HTTP mode is enabled, the server exposes both transport styles:

  • GET|POST|DELETE /mcp for the current Streamable HTTP transport

  • GET /sse plus POST /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

list_bots

read

List bots by type (dca, combo, grid) with filters and field selection

get_bot

read

Get a single bot by id and type

create_bot

write

Create a bot (dca, combo, or grid)

update_bot

write

Update bot settings

clone_bot

write

Clone a bot with optional overrides

manage_bot

write

Lifecycle action: start, stop, archive, restore, changePairs

Deals

Tool

Access

Description

list_deals

read

List deals by type (dca, combo, terminal) with filters

get_deal

read

Get a single deal by id and type

create_deal

write

Create a deal

update_deal

write

Update an active deal

manage_deal

write

Deal action: close, addFunds, reduceFunds

Backtest

Tool

Access

Description

run_backtest

write

Run a backtest: validate, estimate, async, or sync (request/requestSync submit a job — not read-only)

backtest_info

read

List backtest requests or get one by ID

Discovery, Account & Market

Tool

Access

Description

discover

read

Schema discovery for bot types and indicators

get_account

read

Balances, connected exchanges, supported exchanges, and global variables

get_screener

read

Cryptocurrency screener with market metrics

manage_global_variable

write

Global variable action: create, update, delete

Field Selection

All GET endpoints support the fields parameter for efficient payloads:

  • Presets: minimal, standard (default), extended, full

  • Custom: 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, and run_backtest

  • Read-only directory connector (/mcp with GAINIUM_READONLY=true, served at mcp.gainium.io/read): exposes and allows only the 9 readOnlyHint tools — run_backtest and all write tools are excluded

  • Token audience binding (OAuth mode): when GAINIUM_MCP_PUBLIC_URL is set, the server treats <public-url><http-path> as its RFC 8707 resource. An access token whose introspected aud is a different resource is rejected — a token minted for mcp.gainium.io/read can't be replayed against mcp.gainium.io/mcp, and vice versa. Tokens with no aud (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.js

Architecture

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.md

License

MIT

Available Tools

19 tools
apply_presetA
Destructive
Inspect

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_infoA
Read-only
Inspect

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_botA
Destructive
Inspect

Clone an existing bot and optionally override settings. Returns the new bot ID.

Inputs: botType (required), botId (required), paperContext, overrides.

create_botA
Destructive
Inspect

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_dealA
Destructive
Inspect

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.

discoverA
Read-only
Inspect

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_accountB
Read-only
Inspect

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_botA
Read-only
Inspect

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_dealA
Read-only
Inspect

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_screenerC
Read-only
Inspect

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_botsA
Read-only
Inspect

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_dealsA
Read-only
Inspect

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_presetsA
Read-only
Inspect

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_botA
Destructive
Inspect

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_dealB
Destructive
Inspect

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_variableA
Destructive
Inspect

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_botA
Destructive
Inspect

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_dealA
Destructive
Inspect

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

    A3.6/5.0

    Scored across 19 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, covering bots, deals, backtesting, presets, account, screener, and global variables. No two tools overlap in functionality.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Binance USDT-M Futures trading — exposes tools for market data, account state, order management, and position/margin control.
      23
      8
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      An 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to trade crypto with paper money, access market data, view leaderboards, and manage trading bots via an MCP-compatible interface.
      16
      MIT