Gainium

gainium-mcp

Gainium — 暗号資産取引ボットプラットフォーム向けの MCP（Model Context Protocol）サーバーです。標準の MCP インターフェースを通じて、AI アシスタントがボット、取引、残高などを管理できます。

詳細なセットアップと接続方法については、docs/using-gainium-mcp.md をご覧ください。

クイックスタート

1. API キーを取得する

Gainium API Settings に移動し、API キーペアを作成します。

2. MCP クライアントに追加する

以下を MCP の設定に追加します（VS Code、Claude Desktop など）。

{
  "gainium-mcp": {
    "command": "npx",
    "args": ["-y", "gainium-mcp"],
    "env": {
      "GAINIUM_API_KEY": "<your-api-key>",
      "GAINIUM_API_SECRET": "<your-api-secret>"
    }
  }
}

以上です。AI アシスタントが必要としたときに、サーバーが自動的に起動します。

このローカルの stdio モードでは、サーバープロセスの環境から GAINIUM_API_KEY と GAINIUM_API_SECRET を使用します。

環境変数

変数	必須	デフォルト	説明
GAINIUM_API_KEY	はい	—	Gainium API の公開キー
GAINIUM_API_SECRET	はい	—	Gainium API のシークレット
GAINIUM_API_BASE_URL	いいえ	https://api.gainium.io	API のベース URL
GAINIUM_MCP_TRANSPORT	いいえ	stdio	トランスポートモード：stdio、http、streamable-http、sse、または http-sse
GAINIUM_MCP_HOST	いいえ	127.0.0.1	HTTP モードのバインド先ホスト
GAINIUM_MCP_PORT	いいえ	3000	HTTP モードのバインド先ポート
GAINIUM_MCP_HTTP_PATH	いいえ	/mcp	Streamable HTTP エンドポイントのパス
GAINIUM_MCP_SSE_PATH	いいえ	/sse	非推奨の SSE GET エンドポイントのパス
GAINIUM_MCP_MESSAGES_PATH	いいえ	/messages	非推奨の SSE POST エンドポイントのパス
GAINIUM_OAUTH_ISSUER	いいえ	—	認可サーバーのベース URL。これを設定すると（HTTP モードで MCP_INTROSPECTION_SECRET と併せて設定）、OAuth 保護リソースモードが有効になります
GAINIUM_INTROSPECTION_URL	いいえ	<issuer>/oauth/introspect	トークンイントロスペクションエンドポイント
MCP_INTROSPECTION_SECRET	いいえ	—	イントロスペクションエンドポイントに提示する共有シークレット（認証サーバーと一致している必要があります）
GAINIUM_MCP_PUBLIC_URL	いいえ	リクエストから導出	保護リソースのメタデータで使用される公開ベース URL
OPENAI_APPS_CHALLENGE_TOKEN	いいえ	—	設定すると、OpenAI Apps のドメイン検証用に /.well-known/openai-apps-challenge でプレーンテキストとして提供されます

認証モード

gainium-mcp は、次の 3 つのデプロイモデルに対応しています。

• ローカル stdio モード： MCP サーバーは環境変数から GAINIUM_API_KEY と GAINIUM_API_SECRET を読み込みます。
• OAuth 2.1 ホステッドモード（ホステッド環境／公開環境に推奨）： サーバーは OAuth 保護リソースとして動作します。クライアント（Claude コネクターなど）は Gainium 認可サーバーからアクセストークンを取得し、Authorization: Bearer <token> として送信します。詳しくは、以下のOAuth 2.1 ホステッドモードをご覧ください。
• ヘッダーホステッドモード（レガシー／セルフホスト可能）： 各リクエストで X-API-Key と X-API-Secret ヘッダーを送信することで、1 つの共有サーバーを複数のユーザーが利用できます。

ヘッダー／stdio モードでは、リクエストヘッダーが優先され、存在しない場合は GAINIUM_API_KEY／GAINIUM_API_SECRET にフォールバックします。OAuth モードが有効な場合は Bearer トークンが必須となり、X-API-Key／X-API-Secret ヘッダーは無視されます。

OAuth 2.1 ホステッドモード

このモードは、公開エンドポイント https://mcp.gainium.io/mcp と、Anthropic Claude のコネクタディレクトリ（OAuth が必須で、API キーヘッダーは禁止されています）で使用されます。

HTTP モードで次の設定を行うと有効になります。

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

有効にすると、サーバーは次のように動作します。

1. OAuth Protected Resource Metadata（RFC 9728）を /.well-known/oauth-protected-resource と /.well-known/oauth-protected-resource/mcp で提供し、 認可サーバーを通知します。
2. 認証されていない MCP リクエストを 401 Unauthorized と WWW-Authenticate: Bearer resource_metadata="…" ヘッダーで拒否します。これにより、クライアントは 認証サーバーを検出し、OAuth フロー（Dynamic Client Registration + PKCE）を実行できます。
3. リクエストごとに、認証サーバーの トークンイントロスペクション エンドポイントを通じて Bearer アクセストークンを 検証し、ユーザーの Gainium (apiKey, apiSecret) とキーごとの制限（読み取り／書き込み、ペーパー取引のみ、単一ボット）に変換します。 これらの制限は引き続きサーバー側で適用されます。イントロスペクションの結果は短時間キャッシュされます。

ローカルの stdio パスは、これらの変数の影響を受けません。

HTTP および SSE モード

デフォルトでは、gainium-mcp はローカルプロセスを起動する MCP クライアント向けに stdio で実行されます。HTTP サーバーとして実行するには、次のようにします。

export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_MCP_HOST=127.0.0.1
export GAINIUM_MCP_PORT=3000
node dist/server.js

HTTP モードを有効にすると、サーバーは両方のトランスポート方式を公開します。

• 現行の Streamable HTTP トランスポート用の GET|POST|DELETE /mcp
• 非推奨の HTTP+SSE クライアント用の GET /sse と POST /messages?sessionId=...

これにより、1 つのサーバープロセスで最新の MCP HTTP クライアントと旧式の SSE ベースの統合の両方に対応できます。ホステッドモードでは、OAuth で認証してください（OAuth 2.1 ホステッドモードを参照）。セルフホスト環境やレガシー環境では、各リクエストに X-API-Key と X-API-Secret を指定してください。

利用可能なツール（17）

v3.0.0 以降、ツールセットは統合されています。各操作につき 1 つのツールを使用し、バリエーションごとにツールを分ける代わりに、 botType / dealType / action の識別子を使用します。 各ツールには MCP の安全性アノテーションが付与されています。読み取り専用ツールには readOnlyHint、 書き込みツールには destructiveHint が設定されます。

ボット

ツール	アクセス	説明
list_bots	読み取り	フィルターとフィールド選択を指定して、種類（dca、combo、grid）別にボットを一覧表示します
get_bot	読み取り	ID と種類を指定して、単一のボットを取得します
create_bot	書き込み	ボット（dca、combo、grid のいずれか）を作成します
update_bot	書き込み	ボットの設定を更新します
clone_bot	書き込み	オプションの上書き設定を指定して、ボットを複製します
manage_bot	書き込み	ライフサイクル操作：start、stop、archive、restore、changePairs

取引

ツール	アクセス	説明
list_deals	読み取り	フィルターを指定して、種類（dca、combo、terminal）別に取引を一覧表示します
get_deal	読み取り	ID と種類を指定して、単一の取引を取得します
create_deal	書き込み	取引を作成します
update_deal	書き込み	実行中の取引を更新します
manage_deal	書き込み	取引操作：close、addFunds、reduceFunds

バックテスト

ツール	アクセス	説明
run_backtest	書き込み	バックテストを実行します：validate、estimate、非同期、または同期（request／requestSync はジョブを送信します。読み取り専用ではありません）
backtest_info	読み取り	バックテストのリクエストを一覧表示するか、ID を指定して 1 件取得します

検出、アカウント、マーケット

ツール	アクセス	説明
discover	読み取り	ボットの種類とインジケーターのスキーマを検出します
get_account	読み取り	残高、接続済み取引所、対応取引所、グローバル変数を取得します
get_screener	読み取り	マーケット指標を含む暗号資産スクリーナーを取得します
manage_global_variable	書き込み	グローバル変数の操作：create、update、delete

フィールド選択

すべての GET エンドポイントは、ペイロードを効率化するための fields パラメーターをサポートしています。

• プリセット：minimal、standard（デフォルト）、extended、full
• カスタム：ドット記法のフィールドをカンマ区切りで指定します（例：_id,uuid,settings.name,profit.total）

minimal を使用すると、ペイロードサイズを約 85% 削減できます。

API の権限

• 読み取り専用キー：読み取りツールのみ（list_*、get_*、discover、backtest_info、get_screener、list_presets）
• 書き込みキー：create_*、update_*、clone_bot、manage_bot、manage_deal、manage_global_variable、apply_preset、run_backtest など、すべてのツール
• 読み取り専用ディレクトリーコネクター（GAINIUM_READONLY=true を設定した /mcp。mcp.gainium.io/read で提供）：readOnlyHint の 9 つのツールのみを公開して使用できます。run_backtest とすべての書き込みツールは除外されます
• トークンの対象リソースへのバインド（OAuth モード）：GAINIUM_MCP_PUBLIC_URL が設定されている場合、サーバーは <public-url><http-path> を RFC 8707 リソースとして扱います。イントロスペクションで aud が別のリソースと判定されたアクセストークンは拒否されます。mcp.gainium.io/read 用に発行されたトークンを mcp.gainium.io/mcp に対して再利用することはできず、その逆も同様です。aud がないトークン（レガシーグラント）は引き続き受け付けられます。

開発

# 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

アーキテクチャー

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

ライセンス

MIT