Racore Cloud CDN MCP Server

一个基于 Model Context Protocol (MCP) 的 Racore Cloud CDN 管理工具，让 AI 助手（如 Kiro、Claude Desktop、Cursor 等）能够直接管理你的 CDN 加速域名。

功能概览

亮点功能

• 一键创建域名 (quick_create_domain)：只需提供域名和源站，自动匹配/申请 SSL 证书

• 一键查询全部配置 (query_all_domain_config)：一次调用获取域名所有配置信息

• 一键查询全部统计 (query_all_statistics)：一次调用获取域名所有统计数据（流量、请求数、命中率、状态码、Top排行等）

• 智能状态检查：修改配置前自动检查域名状态，state=6 时自动等待（30秒×3次），超时后返回详细等待日志

• 智能等待部署：配置修改时若域名正在部署中(state=6)，自动等待最长 90 秒直到就绪

• 自动证书申请：创建域名时若无匹配证书，自动申请泛域名证书并返回 DNS 验证信息

环境要求

• Node.js >= 18.0.0

• Racore Cloud 账号：需要 Access Key 和 Secret Key（获取方式）

安装步骤

1. 克隆项目

git clone https://github.com/yingcaihuang/racorecloud-mcp.git
cd racorecloud-mcp

或者直接下载 ZIP 解压：

cd ~/Downloads/racorecloud-mcp

2. 安装依赖

npm install

3. 验证安装

node --check index.mjs && echo "✅ 安装成功"

配置 MCP 客户端

方式一：Kiro IDE

在 Kiro 中配置 MCP Server，编辑配置文件：

项目级配置（仅当前项目生效）：

.kiro/settings/mcp.json

全局配置（所有项目生效）：

~/.kiro/settings/mcp.json

添加以下内容：

{
  "mcpServers": {
    "racore-cdn": {
      "command": "node",
      "args": ["/你的路径/racorecloud-mcp/index.mjs"],
      "env": {
        "RACORE_ACCESS_KEY": "你的 Access Key",
        "RACORE_SECRET_KEY": "你的 Secret Key"
      },
      "disabled": false
    }
  }
}

⚠️ 注意：args 中必须使用 绝对路径，不支持相对路径或 cwd 字段。

方式二：Claude Desktop

编辑 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "racore-cdn": {
      "command": "node",
      "args": ["/你的路径/racorecloud-mcp/index.mjs"],
      "env": {
        "RACORE_ACCESS_KEY": "你的 Access Key",
        "RACORE_SECRET_KEY": "你的 Secret Key"
      }
    }
  }
}

方式三：Cursor

在 Cursor 的 Settings → MCP Servers 中添加，或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "racore-cdn": {
      "command": "node",
      "args": ["/你的路径/racorecloud-mcp/index.mjs"],
      "env": {
        "RACORE_ACCESS_KEY": "你的 Access Key",
        "RACORE_SECRET_KEY": "你的 Secret Key"
      }
    }
  }
}

方式四：Amazon Q Developer (Quick Desktop)

1. 复制项目中的 mcp.json 文件内容（修改路径和密钥后）：

{
  "mcpServers": {
    "racore-cdn": {
      "command": "node",
      "args": ["/你的路径/racorecloud-mcp/index.mjs"],
      "env": {
        "RACORE_ACCESS_KEY": "你的 Access Key",
        "RACORE_SECRET_KEY": "你的 Secret Key"
      }
    }
  }
}

2. 打开 Amazon Q Developer Desktop 的 Settings

3. 进入 Capabilities 选项卡

4. 找到 MCP Server 区域，点击 Add MCP Server

5. 类型选择 Local

6. 点击 Paste JSON，粘贴上面的 JSON 内容

7. 保存后 MCP Server 会自动连接

💡 提示：也可以直接将 mcp.json 文件放在项目根目录，Amazon Q 会自动识别。

验证配置

配置完成后，在 AI 助手中尝试：

"查询我的 CDN 域名列表"

如果返回域名信息，说明配置成功。

远程 MCP Server（HTTP 模式）

除了上面的本地 stdio 方式，本项目还支持部署为远程 HTTP MCP Server，供支持 Remote MCP 的客户端（如 Amazon Quick、Cursor 等）通过 URL 连接。两种模式并存，互不影响。

启动 HTTP Server

npm run start:http

默认监听 3000 端口（可通过环境变量 PORT 修改）。端点：

POST  http(s)://<主机>/racorecdn/mcp     # MCP 协议入口
GET   http(s)://<主机>/racorecdn/health  # 健康检查

💡 HTTP 模式采用多租户设计：凭证由客户端在请求 header 中携带，服务端不存储任何密钥。每个租户用自己的 Access/Secret Key，互相隔离。

客户端配置（Remote MCP）

在支持 Remote MCP 的客户端里，粘贴以下 JSON 配置（把 URL 和密钥换成你自己的）：

{
  "mcpServers": {
    "racore-remote-mcp": {
      "url": "https://racore-mcp.verycloud.cn/racorecdn/mcp",
      "headers": {
        "X-Racore-Access-Key": "你的 Access Key",
        "X-Racore-Secret-Key": "你的 Secret Key"
      }
    }
  }
}

本地测试时 URL 用 http://127.0.0.1:3000/racorecdn/mcp。

⚠️ 注意：

• 凭证通过 X-Racore-Access-Key / X-Racore-Secret-Key 两个 header 传递，不是 Authorization。

• 生产环境务必使用 HTTPS（凭证走 header 明文传输），建议前置 Nginx/反向代理做 TLS 终止。

部署

项目内置 Dockerfile、docker-compose.yml（含 Nginx 反向代理）和 GitHub Actions 工作流（.github/workflows/deploy.yml），支持构建镜像推送到 GHCR 并自动部署。证书目录默认挂载自宿主机 /etc/cert/。

获取 API 密钥

1. 登录 Racore Cloud 控制台

2. 进入个人中心 → API 密钥管理

3. 复制 Access Key 和 Secret Key

使用示例

一键创建加速域名

"帮我添加 v2.bbv.cfai.work 源站为 www2.myccdn.info 的加速"

工具会自动：

1. 判断源站类型（IP 或域名）

2. 查找匹配的 SSL 证书

3. 如果没有证书 → 自动申请泛域名证书（DNS 验证方式），等待数秒后返回 CNAME 验证记录

4. 返回的信息包含：证书 ID、验证 CNAME 主机记录和记录值、操作步骤指引

5. 添加 DNS 验证记录后，证书签发（通常 5-30 分钟），再次调用即可完成创建

6. 如果有证书 → 直接创建域名并开启 SSL

查询域名全部配置

"查询 v1.bbv.cfai.work 的全部配置"

一次返回源站、HTTPS、压缩、缓存、访问控制等所有配置信息。

修改域名配置

"把 v1.bbv.cfai.work 的 HTTP/2 开启"

工具会：

1. 先检查域名状态（必须是 state=1 启用中）

2. 如果正在部署中（state=6）→ 自动等待 30 秒后重试，最多重试 3 次（最长等 90 秒）

3. 等待期间输出进度日志，如：⏳ 域名正在配置发布中，等待 30 秒后重试 (1/3)...

4. 就绪后自动执行配置修改；超时则返回详细等待过程说明

统计查询

"查询 v1.bbv.cfai.work 的所有统计数据"

一次调用返回全部统计：流量、请求数、地区分布、缓存命中率、HTTP 状态码、Top URL/Referer/UA。

"查询这个月的 CDN 流量 Top 域名"

"查询 v1.bbv.cfai.work 昨天的请求数"

内容刷新

"刷新 https://v1.bbv.cfai.work/index.html 的缓存"

证书管理

"查看我的证书列表"

"为 *.newdomain.com 申请 SSL 证书"

工单管理

"创建一个工单，标题是'域名配置异常'，内容是..."

"查看我的工单列表"

完整工具列表

域名操作 (domain-operations)

域名配置 (domain-config)

证书管理 (certificate)

内容管理 (content-management)

统计分析 (statistics)

日志管理 (log-management)

工单管理 (workorder)

项目结构

racorecloud-mcp/
├── index.mjs              # 入口文件：MCP Server 初始化
├── auth.mjs               # 认证模块：HMAC-SHA512 签名 + Token 缓存
├── api-client.mjs         # API 客户端：HTTP 请求封装（GET/POST/PUT/DELETE）
├── validators.mjs         # 参数校验器：时间格式、范围验证
├── tools/
│   ├── domain-operations.mjs   # 域名操作（创建/启用/停用/删除）
│   ├── domain-config.mjs       # 域名配置（全部查询/设置工具）
│   ├── certificate.mjs         # 证书管理
│   ├── content-management.mjs  # 内容刷新/预热
│   ├── cdn-traffic.mjs         # CDN 流量查询
│   ├── region-traffic.mjs      # 地区流量查询
│   ├── request-count.mjs       # 请求数查询
│   ├── statistics.mjs          # 其他统计工具
│   ├── log-management.mjs      # 日志管理
│   └── workorder.mjs           # 工单管理
├── package.json
└── mcp.json               # MCP 配置示例

常见问题

Q: 提示 "环境变量未设置"

确保在 MCP 配置的 env 中正确填写了 RACORE_ACCESS_KEY 和 RACORE_SECRET_KEY。

Q: 工具调用返回 "No route found"

部分接口可能在你的账户套餐中不可用。这不影响其他工具的使用。

Q: 修改配置提示 "配置发布中"

工具会自动等待域名部署完成（最长 90 秒），期间会输出等待进度。如果超时仍未就绪，会返回完整的等待过程日志。你可以稍后再试，或通过 get_domain_list 查看域名状态。

Q: 一键创建域名提示需要 DNS 验证

首次使用某个新的域名后缀时，需要申请 SSL 证书。按照返回的 CNAME 记录添加 DNS 后，等待证书签发，再次调用即可。

Q: 如何在多个客户端之间共享配置？

将项目路径和密钥写入各客户端的 MCP 配置文件即可。密钥建议通过环境变量注入，避免明文存储。

技术规格

• 运行时: Node.js 18+

• 模块系统: ES Module (.mjs)

• 协议: MCP (Model Context Protocol) via stdio

• 认证: HMAC-SHA512 签名 + Bearer Token（自动缓存和刷新）

• 超时: 所有 API 请求 30 秒超时

• 重试: 401 自动重新认证并重试一次

• API 基础地址: https://portal.racorecloud.com

License

MIT