# carbonstop-mcp

MCP (Model Context Protocol) server for Carbonstop — 碳阻迹碳足迹核算 MCP 服务。

AI 对话中自动调用碳云 API，完成碳足迹建模、产品查询、核算分析。

## Install

### npx (recommended)

No install needed. Use directly in MCP config or terminal:

```bash
npx @carbonstopper/mcp --api-key csk_xxx.yyy
```

### npm

```bash
npm install -g @carbonstopper/mcp
```

### Download binary

Download the latest binary from [Releases](https://github.com/carbonstop-hub/carbonstop-mcp/releases/latest):

| Platform | File |
|----------|------|
| macOS Apple Silicon | `carbonstop-mcp_*_darwin_arm64.tar.gz` |
| macOS Intel | `carbonstop-mcp_*_darwin_x86_64.tar.gz` |
| Linux x86_64 | `carbonstop-mcp_*_linux_x86_64.tar.gz` |
| Linux arm64 | `carbonstop-mcp_*_linux_arm64.tar.gz` |
| Windows x86_64 | `carbonstop-mcp_*_windows_x86_64.zip` |

```bash
curl -L https://github.com/carbonstop-hub/carbonstop-mcp/releases/latest/download/carbonstop-mcp_linux_x86_64.tar.gz | tar xz
sudo mv carbonstop-mcp /usr/local/bin/
```

### Build from source

Requires **Go 1.23+**.

```bash
git clone https://github.com/carbonstop-hub/carbonstop-mcp.git
cd carbonstop-mcp
make build
```

## Quick Start

1. 登录 [碳云平台](https://ccloud-d-test.carbonstop.com/) 注册账号，创建 API Key（PAT）
2. 启动：

```bash
export CARBONSTOP_API_KEY="csk_xxx.yyy"
./carbonstop-mcp
# 或
npx @carbonstopper/mcp --api-key csk_xxx.yyy
```

> 官方版已内置网关地址。自编译需设置 `CARBONSTOP_BASE_URL`。

## Agent Configuration

### npx (零安装，推荐)

```json
{
  "mcpServers": {
    "carbonstop": {
      "command": "npx",
      "args": ["@carbonstopper/mcp", "--api-key", "csk_xxx.yyy"]
    }
  }
}
```

### 全局安装

```json
{
  "mcpServers": {
    "carbonstop": {
      "command": "carbonstop-mcp",
      "args": ["--api-key", "csk_xxx.yyy"]
    }
  }
}
```

### 直接二进制路径

```json
{
  "mcpServers": {
    "carbonstop": {
      "command": "/usr/local/bin/carbonstop-mcp",
      "args": ["--api-key", "csk_xxx.yyy"]
    }
  }
}
```

Claude Code、Cursor、Windsurf、Codex、Hermes 等 MCP 客户端配置格式相同。

## Available Tools

| Tool | Description |
|------|-------------|
| `ping` | 网关探活 |
| `whoami` | 查看身份信息 |
| `products` | 产品列表（支持分页、搜索） |
| `product_info` | 产品详情 |
| `accounts` | 产品核算列表 |
| `account_view` | 核算详情（含生命周期各阶段排放） |
| `ai_model` | 一键 AI 碳足迹建模 |

## Security

- 网关地址构建时注入，源码中不可见
- API Key 通过 `--api-key` 参数或环境变量传入

## Related

- [carbonstop-cli](https://github.com/carbonstop-hub/carbonstop-cli) — 命令行工具

## License

MIT