Riveter

Riveter MCP 服务

一个 MCP（模型上下文协议）服务，可将 Claude 和 Cursor 等 AI 助手连接到 Riveter API。直接通过助手运行数据丰富、构建数据集、抓取网页、管理监控项等操作。

工具根据 Riveter 的 OpenAPI 规范动态生成，因此会自动保持最新。

有两种连接方式：

• 托管式 — https://mcp.riveterhq.com/mcp。无需安装。支持 claude.ai、Claude Desktop、Cowork、Claude mobile、ChatGPT、Claude Code 和 Cursor。
• 本地（npx） — 此 npm 包，可在你的机器上通过 stdio 运行。当客户端无法连接远程服务时使用。

设置

1a. 托管式服务（无需预先提供 API 密钥）

添加 https://mcp.riveterhq.com/mcp 作为自定义连接器，然后点击 Connect。浏览器窗口会打开 Riveter：登录并点击 Allow。Riveter 会为该连接创建一个 API 密钥；你可以在设置 → API 密钥中查看，撤销该密钥即可断开客户端连接。

Claude Code：

claude mcp add --transport http riveter https://mcp.riveterhq.com/mcp

然后运行 /mcp 并选择 Authenticate。

Cursor：

{
  "mcpServers": {
    "riveter": {
      "url": "https://mcp.riveterhq.com/mcp"
    }
  }
}

如果客户端无法打开浏览器，请改为通过标头传递密钥：Authorization: Bearer sk_riv_your_key_here（Claude Code 使用 --header "Authorization: Bearer sk_riv_..."，Cursor 使用 "headers": { "Authorization": "Bearer sk_riv_..." }）。

1b. 本地服务（npx）

前往 app.riveterhq.com/settings/api 获取 Riveter API 密钥。

Claude Desktop — 打开配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

添加 Riveter 服务：

{
  "mcpServers": {
    "riveter": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "riveter-mcp-server@latest"],
      "env": {
        "RIVETER_API_KEY": "sk_riv_your_key_here"
      }
    }
  }
}

Cursor / Windsurf — 将相同的 riveter 条目添加到你的 MCP 配置中（例如 ~/.cursor/mcp.json）。

Claude Code：

claude mcp add riveter --env RIVETER_API_KEY=sk_riv_your_key_here -- npx -y riveter-mcp-server

Codex：

codex mcp add riveter --env RIVETER_API_KEY=sk_riv_your_key_here -- npx -y riveter-mcp-server

**保持工具为最新：**本地服务会在客户端启动时加载一次 API 定义，并持续运行该进程。Riveter 发布 API 更改后，重启 AI 客户端（或在设置页面重启 MCP 服务）即可加载新工具。使用 --prefer-online riveter-mcp-server@latest，同一次重启还会获取新版本的服务。托管式服务无需重启；它每 10 分钟重新加载一次 API 定义。

环境变量

本地（stdio）服务 — dist/index.js：

变量	必需	默认值	描述
RIVETER_API_KEY	是	—	你的 Riveter API 密钥
RIVETER_API_BASE_URL	否	https://api.riveterhq.com/v1	API 基础 URL
RIVETER_OPENAPI_URL	否	https://docs.riveterhq.com/openapi.yaml	OpenAPI 规范 URL。https://docs.riveterhq.com/openapi.legacy.yaml 提供旧版接口（动词端点、旧版 enrichments、已停用的 list-build 操作）

托管（Streamable HTTP）服务 — dist/http.js，由 Riveter 部署：

变量	默认值	描述
PORT	8080	监听端口
MCP_PUBLIC_URL	https://mcp.riveterhq.com/mcp	公共 URL，必须与用户输入的内容完全一致（RFC 9728 resource）
OAUTH_ISSUER_URL	https://app.riveterhq.com	在受保护资源元数据中公布的授权服务器
SPEC_REFRESH_INTERVAL_MS	600000	重新获取规范的频率；0 表示禁用
RIVETER_API_BASE_URL、RIVETER_OPENAPI_URL	同上

托管服务不保存 API 密钥。它会在每次调用时将调用方的 Authorization: Bearer ... 标头转发给 API，并在缺少该标头时通过 WWW-Authenticate 质询响应 401。

工作原理

启动时，服务会：

1. 从 docs.riveterhq.com/openapi.yaml 获取 OpenAPI 规范
2. 将每个端点解析为带有类型化参数和注解的 MCP 工具（readOnlyHint 来自 GET，destructiveHint 来自 DELETE 或规范中的 x-mcp-destructive，openWorldHint 来自规范中的 x-mcp-open-world）
3. 使用规范中的 info.x-mcp-instructions 作为简短的服务级 instructions（较长的 API 概述仍保留在文档网站上）；设置操作的 x-mcp-description 后，它会替代该工具的 description
4. 添加一个 help 工具，其主题（列配置、格式、工具、run_when、示例、额度、限制、错误等）来自规范中的 info.x-mcp-help——只有助手请求时才会加载详细说明
5. 通过 stdio（本地）或 Streamable HTTP（托管）提供这些工具

API 文档更新后，本地服务会在助手下次启动时获取变更；托管服务则每 10 分钟重新获取一次规范——无需重新构建或发布。

开发

源码：github.com/riveterhq/riveter-mcp。欢迎在此提交问题。

npm install
npm test          # build + unit + stdio e2e + http e2e
npm run dev:http  # hosted server on :8080 (set MCP_PUBLIC_URL=http://localhost:8080/mcp)

此仓库是 Riveter 私有单体仓库中 mcp-server/ 目录的只读镜像，开发工作在该单体仓库中进行。规范契约测试需要单体仓库中的 openapi.yaml，因此在此处会跳过。发布说明见 PUBLISHING.md。

支持

有疑问或遇到问题？请查看 Riveter API 文档，或联系 [email protected]。

许可证

MIT