内容
# Coinbase MCP 服务器（coinbase-mcp）
[](https://github.com/rangertaha/coinbase-mcp/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/rangertaha/coinbase-mcp)
[](go.mod)
[](LICENSE)
一个 **Coinbase** [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，使用 Go 编写，暴露 Coinbase 高级交易 API 作为工具，供 LLM 客户端（Claude Desktop/Code、Cursor 等）调用。查看 [**文档**](https://rangertaha.github.io/coinbase-mcp/) 以获取更多详细信息。
**在本 README 中**，大致从浅到深：[安装](#安装) → [功能](#功能) → [配置](#配置) → [命令行界面](#命令行界面) → [工具集](#工具集) → [工具](#工具) → [提示（工作流）](#提示（工作流）) → [架构](#架构) → [开发](#开发) → [变更日志](#变更日志)。 [文档网站](https://rangertaha.github.io/coinbase-mcp/) 镜像此相同路径作为单独的页面，如果您不想滚动。
## 安装
```sh
go install github.com/rangertaha/coinbase-mcp/cmd/coinbase@latest
```
这会在您的 `$GOBIN` 中放置一个 `coinbase` 二进制文件。
<details>
<summary><strong>从源代码构建</strong></summary>
```sh
git clone https://github.com/rangertaha/coinbase-mcp
cd coinbase-mcp
make build # 生成 ./bin/coinbase
```
</details>
发布版本由标签触发（通过 CI 使用 GoReleaser），并在 [发布页面](https://github.com/rangertaha/coinbase-mcp/releases) 上发布针对 macOS、Linux 和 Windows（amd64/arm64）的预构建存档，一旦标记第一个版本。
由于市场数据是公开的，因此服务器在**无需凭证**的情况下开箱即用 - 安装它，将其连接到您的 MCP 客户端，然后询问价格。
## 功能
- **默认公开**：市场数据工具无需凭证；将 MCP 客户端指向二进制文件即可使用。
- **具有模式的键入工具**：每个工具都有一个自动生成的 JSON 模式用于输入和输出，从 Go 结构体推断，具有每个字段的描述。在处理程序运行之前，输入将被验证。
- **只读开关**：`COINBASE_READONLY=true` 隐藏每个变异工具（订单放置、取消、投资组合更改，...）；只读 CDP 密钥（can_trade=false）在注册时自动强制执行，因此服务器可以安全地指向一个有资金的账户。
- **工具集过滤**：使用 `COINBASE_TOOLSETS` 启用您需要的区域，以保持工具列表聚焦。
- **构建在官方 SDK 上**：使用 [`modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk) （v1）。
- **`.env` 支持**：对于本地开发，工作目录中的 `.env` 文件在启动时加载；实际环境变量优先。
## 配置
所有配置均从环境中读取。**每个变量都是可选的** - 不设置任何变量，服务器将提供公共市场数据。
| 变量 | 必需 | 描述 |
| --------------------- | :--: | ------------------------------------------------------------------------------------------------------------------------------------ |
| `COINBASE_API_KEY` | 否 | CDP API 密钥名称，来自 [Coinbase 开发者平台](https://portal.cdp.coinbase.com/)。启用身份验证的工具集（账户、订单、投资组合，...）；设置密钥和密码或两者皆可。每个请求都使用短期 CDP JWT（ES256 或 Ed25519 密钥）签名。 |
| `COINBASE_API_SECRET` | 否 | CDP API 私钥。 |
| `COINBASE_BASE_URL` | 否 | API 基本 URL（默认 `https://api.coinbase.com`）。 |
| `COINBASE_TOOLSETS` | 否 | 以逗号分隔的工具集名称列表，或 `all`（默认）。 |
| `COINBASE_TOOLS` | 否 | 在启用的工具集中允许的单个工具名称的逗号分隔列表。 |
| `COINBASE_READONLY` | 否 | 为真（`1`、`true`、`yes`、`on`）以仅公开只读工具。 |
仅设置 `COINBASE_API_KEY`/`COINBASE_API_SECRET` 中的一个会被启动时拒绝 - 半设置对几乎肯定是一个错误。
### 与 Claude Desktop / Claude Code 结合使用
添加到您的 MCP 客户端配置（例如 `claude_desktop_config.json`）；`env` 块仅在存在身份验证工具集时需要：
```json
{
"mcpServers": {
"coinbase": {
"command": "coinbase",
"args": ["mcp"]
}
}
}
```
对于 Claude Code：`claude mcp add coinbase -- coinbase mcp`.
### 本地开发
存储库附带一个已提交的 [.mcp.json](.mcp.json)，可以直接从源代码运行服务器（`go run ./cmd/coinbase mcp`），因此更改会在下一个会话中生效，无需构建步骤。它从环境中读取凭证（存储库中没有机密）。如果您需要凭证，请运行 `cp .env.example .env` 并填写 - 服务器在启动时从工作目录加载 `.env`。
## 命令行界面
`coinbase` 是一个小型命令树（构建在 urfave/cli 上）。没有子命令的裸 `coinbase` 等同于 `coinbase mcp`.
- `coinbase mcp`: 在 stdio 上运行 MCP 服务器。这是 MCP 客户端（Claude Desktop/Code、Cursor）调用的内容。
- `coinbase test`: 与 Coinbase API 进行连接测试（请求一个公共产品并报告可用产品数量）：
```
$ coinbase test
OK connected to https://api.coinbase.com (792 products available)
authenticated=false read-only=false
```
## 工具
工具遵循命名约定 `<toolset>_<action>`。变异工具标记为 **[write]** （和 **[destructive]**，其中它们取消或删除）并在 `COINBASE_READONLY=true` 时隐藏。
### 产品（公开）
- `products_list`: 列出可交易的 Coinbase 产品（市场）及其当前价格和 24 小时统计数据。可选地按产品类型（例如 `SPOT` 或 `FUTURE`）过滤并限制返回的数量。
- `products_get`: 通过 ID 获取单个 Coinbase 产品，例如 `BTC-USD` - 价格、24 小时百分比变化、24 小时交易量、基础/报价名称、状态和是否启用交易。
- `products_candles`: 获取产品在一段时间范围内的 OHLCV 价格历史（蜡烛），粒度从一分钟到一天。
- `products_ticker`: 获取最近的市场交易和产品的当前最佳出价/要价。
- `products_book`: 获取产品的订单簿（出价和要价），可选限制为前 N 个级别。
- `products_time`: 获取 Coinbase API 服务器时间（ISO 和 UNIX 时间戳）。
- `products_best_bid_ask`: 获取多个产品的当前最佳出价/要价（顶级订单）（需要凭证）。
### 账户
- `accounts_list`: 列出身份验证用户的交易账户（钱包）及其可用和持有余额；基于光标分页。
- `accounts_get`: 通过 UUID 获取单个交易账户。
### 订单
- `orders_create` **[write]**: 下订单。类型：`market`（BUY 使用 `quoteSize`，SELL 使用 `baseSize`）、`limit`、`limit_fok`、`sor_limit`、`stop_limit`（`stopPrice` + `stopDirection`）和 `bracket`（`stopTriggerPrice`）；非市场类型使用 `baseSize` 和 `limitPrice`，可选 `endTime` 表示有效期至当天。`takeProfitPrice`+`stopLossPrice` 附加一个 TP/SL 支架，在父订单填充时退出。实际资金移动 - 预览第一。
- `orders_preview`: 模拟下订单 - 投影总金额、费用、滑点和任何错误 - 无需下订单。
- `orders_edit` **[write]**: 编辑现有开放的限价订单的价格和数量。
- `orders_edit_preview`: 模拟订单编辑并获取预测结果而无需更改订单。
- `orders_cancel` **[write, destructive]**: 取消一个或多个开放订单，订单 ID 具有每个订单的结果。
- `orders_close_position` **[write, destructive]**: 下订单以关闭开放仓位，可选部分关闭。
- `orders_list`: 列出历史订单，可按产品、状态和侧面过滤；基于光标分页。
- `orders_get`: 通过 ID 获取单个订单，包括状态和填充详细信息。
- `orders_fills`: 列出填充（执行），可按订单和/或产品过滤；基于光标分页。
### 投资组合
- `portfolios_list`: 列出投资组合，可选按类型过滤。
- `portfolios_get`: 获取投资组合的明细：聚合余额和现货仓位。
- `portfolios_create` **[write]**: 创建新投资组合。
- `portfolios_edit` **[write]**: 重命名投资组合。
- `portfolios_delete` **[write, destructive]**: 通过 UUID 删除投资组合。
- `portfolios_move_funds` **[write]**: 在投资组合之间移动一定数量的货币。
### 转换
- `convert_quote` **[write]**: 创建报价以在两个账户之间转换金额（例如 USD 至 USDC）。
- `convert_commit` **[write]**: 提交先前创建的报价，执行转换。
- `convert_get`: 通过 ID 获取转换交易的狀態。
### 费用
- `fees_summary`: 获取交易量、已付费用和当前的做市商/接受者费用等级。
### 支付
- `payments_list`: 列出链接的支付方式及其允许的操作（购买/出售/存款/取款）。
- `payments_get`: 通过 ID 获取单个支付方式。
### 期货（CFM）
- `futures_balance`: 期货余额摘要：购买力、保证金、清算水平。
- `futures_positions`: 列出所有开放的美国期货仓位。
- `futures_position`: 获取单个产品的开放期货仓位。
- `futures_sweeps`: 列出期货和现货之间的待处理/正在处理的 USD 扫荡。
- `futures_sweep_schedule` **[write]**: 将 USD 扫荡到现货钱包。
- `futures_sweep_cancel` **[write, destructive]**: 取消待处理的扫荡。
- `futures_margin_setting`: 获取日内保证金设置。
- `futures_margin_setting_set` **[write]**: 设置日内保证金设置。
- `futures_margin_window`: 获取当前保证金窗口和杀死开关状态。
### 永续合约（INTX）
- `perpetuals_portfolio`: 投资组合摘要：抵押品、保证金、清算状态。
- `perpetuals_positions`: 列出投资组合中的所有开放永续合约仓位。
- `perpetuals_position`: 获取单个符号的开放仓位。
- `perpetuals_balances`: 永续合约投资组合的资产余额。
- `perpetuals_allocate` **[write]**: 将抵押品分配给隔离仓位。
- `perpetuals_multi_asset_collateral` **[write]**: 启用/禁用多资产抵押品。
### 密钥
- `keys_permissions`: 获取使用的 API 密钥的权限（查看/交易/转账）及其投资组合范围。
## 提示（工作流）
提示是用户调用的模板，MCP 客户端将其显示为 **斜杠命令**（例如在 Claude Code 和 Claude Desktop 中）。每个提示都引导模型通过一系列工具调用。内置提示：
| 提示 | 参数 | 它执行的操作 |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `market_snapshot` | product | 加载产品的价格、24 小时变化和交易量，然后总结市场 |
## 架构
<details>
<summary>项目布局</summary>
```
cmd/coinbase 入口点：urfave/cli 命令树（mcp, test）
internal/config 环境配置 + 验证，.env 加载
internal/client 通用 JSON REST 客户端（可插拔身份验证，错误映射）
internal/server MCP 服务器包装器，键入工具注册，只读策略
internal/coinbase Coinbase API 连接（共享 REST 客户端）+ 连接检查
internal/coinbase/<area> 每个 API 区域一个包：<area>.go（操作）+ tools.go（工具）
internal/prompts 内置工作流提示
internal/app 从配置中组装配置的服务器
```
`mcp` 子命令加载配置，注册启用的工具集，并通过 stdio 提供服务；`test` 检查连接性。
每个 API 区域都遵循相同的形状：包装共享 REST 客户端的 `service` 暴露类型化操作，`Register` 函数为它们注册薄的 MCP 工具处理程序。添加新区域只需插入一个包并在 `internal/app` 中列出它。有关完整的请求流程演练，请参阅 [文档网站的架构页面](https://rangertaha.github.io/coinbase-mcp/architecture/)。
</details>
## 开发
<details>
<summary>构建、测试和烟雾测试</summary>
```sh
make test # go test -race ./...
make cover # 运行测试并打印覆盖率摘要
make vet # go vet ./...
make fmt-check # gofmt 验证
make lint # golangci-lint
make all # fmt-check + vet + lint + test + build
```
发布版本由标签触发（通过 CI 使用 GoReleaser）；`make next`/`make bump` 从传统提交中计算并标记下一个版本。有关完整的发布工作流程，请参阅 [文档网站的开发页面](https://rangertaha.github.io/coinbase-mcp/development/)。
### 协议的烟雾测试
无需 MCP 客户端（无需凭证）即可通过 stdio 列出工具：
```sh
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"s","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| ./bin/coinbase mcp
```
或使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行交互式浏览：
```sh
npx @modelcontextprotocol/inspector ./bin/coinbase mcp
```
</details>
## 变更日志
请参阅 [CHANGELOG.md](CHANGELOG.md)。
## 许可证
MIT。 请参阅 [LICENSE](LICENSE)。
