Gainium

gainium-mcp

适用于 Gainium 的 MCP（Model Context Protocol）服务——一个加密货币交易机器人平台。通过标准 MCP 接口，让 AI 助手管理你的机器人、交易、余额等。

详细的设置和连接文档请参阅 docs/using-gainium-mcp.md。

快速开始

1. 获取 API 密钥

前往 Gainium API 设置并创建一对 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	否	—	设置后，将以纯文本形式通过 /.well-known/openai-apps-challenge 提供，用于 OpenAI Apps 域名验证

身份验证模式

gainium-mcp 支持三种部署模式：

• 本地 stdio 模式： MCP 服务从环境变量中读取 GAINIUM_API_KEY 和 GAINIUM_API_SECRET。
• OAuth 2.1 托管模式（推荐用于托管/公开部署）： 服务充当 OAuth 受保护资源。客户端（例如 Claude 连接器）从 Gainium 授权服务器获取访问令牌，并将其作为 Authorization: Bearer <token> 发送。请参阅下文的 OAuth 2.1 托管模式。
• Header 托管模式（旧版/可自托管）： 每个请求都会发送 X-API-Key 和 X-API-Secret 标头，使一个共享服务能够为多个用户提供服务。

在 header/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. 在 /.well-known/oauth-protected-resource 和 /.well-known/oauth-protected-resource/mcp 提供 OAuth 受保护资源元数据（RFC 9728），并公布授权服务器。
2. 使用 401 Unauthorized 拒绝未经身份验证的 MCP 请求，并返回 WWW-Authenticate: Bearer resource_metadata="…" 标头，让客户端发现授权服务器并运行 OAuth 流程（动态客户端注册 + PKCE）。
3. 在每次请求时，通过授权服务器的 令牌内省端点验证 Bearer 访问令牌，并将其解析为用户的 Gainium (apiKey, apiSecret) 及每个密钥的限制（读/写、仅模拟盘、单个机器人）；这些限制仍由服务端强制执行。内省结果会短暂缓存。

本地 stdio 路径不受这些变量影响。

HTTP 和 SSE 模式

默认情况下，gainium-mcp 通过 stdio 运行，供启动本地进程的 MCP 客户端使用。若要改为以 HTTP 服务运行：

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

启用 HTTP 模式后，服务会同时提供两种传输方式：

• GET|POST|DELETE /mcp，用于当前的 Streamable HTTP 传输
• GET /sse 和 POST /messages?sessionId=...，用于已弃用的 HTTP+SSE 客户端

这样，同一个服务进程即可兼容现代 MCP HTTP 客户端和较旧的 SSE 集成。在托管模式下，请使用 OAuth 进行身份验证（参见 OAuth 2.1 托管模式）；对于可自托管／旧版设置，请在每次请求中发送 X-API-Key 和 X-API-Secret。

可用工具（17 个）

从 v3.0.0 开始，工具集已合并：每种操作对应一个工具，并使用 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 获取一项请求

发现、账户和市场

工具	访问权限	说明
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
• 只读目录连接器（/mcp，设置 GAINIUM_READONLY=true，服务地址为 mcp.gainium.io/read）：仅公开并允许使用 9 个 readOnlyHint 工具；不包含 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