Rollbar Mcp Server

rollbar-mcp-server

适用于 Rollbar 的模型上下文协议（MCP）服务。

功能

此 MCP 服务实现了 stdio 服务类型，这意味着你的 AI 工具（例如 Claude、Cursor）会直接运行它；你无需运行单独的进程或通过 HTTP 连接。

配置

用户访问令牌

要读取项目历史记录并以自己的身份发布评论，请使用 ROLLBAR_USER_ACCESS_TOKEN 配置 Rollbar 用户级账户访问令牌，或使用配置文件：

{ "userToken": "<user access token>" }

读取时使用 read 权限范围，发布评论时使用 read and write 权限范围。MCP 会通过 GET /projects（read 权限范围）解析你的项目，然后使用 write 权限范围发布评论。你的 Rollbar 用户还需要具有该项目的 view 权限才能读取历史记录，以及 comment 权限才能发布评论。项目令牌和普通账户令牌无法发布评论。

用户模式下的每个请求都会使用已配置用户的令牌发送，即使同时存在项目令牌也是如此。评论作者身份取决于该令牌；你无法指定其他作者。后端会将已发布的评论标记为 via_api: true，并处理常规订阅和通知。

请只配置 userToken / ROLLBAR_USER_ACCESS_TOKEN 或 accountToken / ROLLBAR_ACCOUNT_ACCESS_TOKEN 中的一项。两者都配置时，启动会失败，包括一项来自文件、另一项来自环境变量的情况。对于同一种令牌类型，文件中的值会覆盖环境变量中的值。文件中的 apiBase 或仅通过环境变量配置时的 ROLLBAR_API_BASE 可用于选择自定义 API 端点。

使用 list-projects 查找工具的 project 参数所需的项目名称或数字 ID。如果你的用户令牌只能看到一个已启用项目，则此参数可选。仅通过旧版 ROLLBAR_ACCESS_TOKEN 设置提供的令牌不会被推断为用户令牌；要发布评论，请显式设置 ROLLBAR_USER_ACCESS_TOKEN。

账户访问令牌

配置单个 Rollbar Account Access Token，即可读取和更新该账户中各项目的项目。发布评论需要使用上文所述的用户模式：

• ROLLBAR_ACCOUNT_ACCESS_TOKEN（环境变量），或
• accountToken（.rollbar-mcp.json 中的顶层键，与 projects/token/apiBase 并列）

创建方式：在 Rollbar 中，前往 账户设置 → Account Access Tokens，创建一个新的、已启用且带名称的令牌，并选择 read 权限范围（如果计划使用 update-item，则选择 read and write）。立即复制生成的完整密钥，Rollbar 只会显示一次；请妥善保管（存放在密钥管理器或 shell 的环境变量配置中，不要提交到源代码管理中）。

{
  "accountToken": "acct_tok_abc123"
}

如果你希望对某些项目实施更严格的控制，可以为账户令牌设置 read 权限范围，以便读取所有项目，然后明确列出少数需要 update-item 的项目，并为它们配置各自的 read+write 项目令牌。根据下文的优先级规则，这些令牌只会覆盖对应项目的账户令牌（显式配置的项目令牌始终优先）。

{
  "accountToken": "acct_tok_abc123",
  "projects": [
    { "name": "backend", "token": "tok_backend_readwrite" }
  ]
}

此功能不会改变项目令牌配置：如果你未设置账户令牌，现有的单项目或多项目配置行为完全不变。两种模式也可以共存：如果 project 名称与一个显式配置且拥有自身令牌的项目匹配，那么无论是否配置了账户令牌，该项目始终使用自己的令牌。

按项目配置，实现更安全的访问

单个项目：环境变量

• ROLLBAR_ACCESS_TOKEN：Rollbar 项目的访问令牌。
• ROLLBAR_API_BASE（可选）：覆盖 API 基础 URL（默认为 https://api.rollbar.com/api/1）。

多个项目：配置文件

在工作目录或主目录中创建 .rollbar-mcp.json，或者将 ROLLBAR_CONFIG_FILE 设置为自定义路径。仓库中提供了一个模板 rollbar-mcp-example.json；将其复制为 .rollbar-mcp.json，然后填入真实令牌。

单项目简写：

{ "token": "tok_abc123" }

多个项目：

{
  "projects": [
    { "name": "backend",  "token": "tok_abc123" },
    { "name": "frontend", "token": "tok_xyz789" }
  ]
}

配置文件查找顺序：

1. ROLLBAR_CONFIG_FILE 环境变量
2. 当前工作目录中的 .rollbar-mcp.json
3. 主目录中的 ~/.rollbar-mcp.json
4. ROLLBAR_ACCESS_TOKEN、ROLLBAR_ACCOUNT_ACCESS_TOKEN 或 ROLLBAR_USER_ACCESS_TOKEN 环境变量

如果配置文件存在但无效，服务会报错退出，而不会回退到优先级较低的配置来源。

所需权限范围：

• 只读工具（get-item-details、get-deployments、get-version、get-top-items、list-items、get-replay、list-projects、list-occurrences、list-item-events）可使用具有 read 权限范围的账户或用户令牌，但仍受项目权限限制。
• update-item 需要同时具有 read 和 write 权限范围的账户令牌：每次使用账户令牌的调用都会先通过 GET /projects 解析目标项目（read），然后发出 PATCH 请求（write）。只有 write 权限的令牌会在项目解析步骤失败，无法执行更新。
• 与项目令牌一样，除非你确实需要使用 update-item，否则建议使用 read 权限范围的令牌。
• post-item-comment 需要具有 read 和 write 权限范围且拥有项目 comment 权限的用户令牌。

如果服务检测到只设置了 ROLLBAR_ACCESS_TOKEN（未显式设置账户令牌），就会通过 GET /projects 进行一次性缓存检查，以确定该令牌是否为账户令牌；如果是，则会自动启用账户模式。单项目范围的令牌仍会像以前一样正常使用。

工具

list-projects()：查看此服务可以访问哪些 Rollbar 项目。如果你使用的是单项目令牌，这里只会确认你配置的那个项目。如果你使用的是可访问多个项目的账户令牌，可通过此工具查找项目名称或 ID，以便传入其他工具的 project 参数。

get-item-details(counter, max_tokens?, project?)：查看单个 Rollbar 条目的完整信息，包括条目详情及其最近一次出现记录，无需先查找条目再单独获取最新错误。传入条目的计数器（Rollbar UI 中显示的数字）。

max_tokens（默认值为 20000）用于限制响应中出现记录数据的大小。有些出现记录包含大量详细信息（长堆栈跟踪、请求数据），此参数可避免单次条目查询导致响应过大。可选的 project 用于选择要使用的项目；在账户令牌模式下，可按已配置的名称或真实项目名称／ID 选择。提示词示例：诊断 Rollbar 条目 #123456 的根本原因

get-deployments(limit, project?)：列出项目最近的部署，以便对照部署时间与错误开始或停止出现的时间。配置了多个项目或处于账户令牌模式时，可选填 project。提示词示例：列出最近 5 次部署 或 有没有失败的部署？

get-version(version, environment, project?)：查询特定版本（例如 git SHA）在某个环境中的表现，包括该版本首次和最近一次出现在错误记录中的时间。适用于检查某个版本是否引入或修复了问题。配置了多个项目或处于账户令牌模式时，可选填 project。 get-top-items(environment, project?)：查看当前实际出现最多的问题。返回指定环境最近 24 小时内出现次数最多的问题，方便你优先排查，而不必浏览完整的问题列表。配置了多个项目或使用账户令牌模式时，可选填 project。

list-items(status?, level?, environment?, page?, limit?, query?, project?)：搜索和筛选 Rollbar 问题，而不是获取整个列表。可按 status（默认为 active，因此已解决和已静音的问题不会干扰你）、level 和 environment 筛选，也可按 query 文本搜索。使用 page 和 limit 控制每次返回的数量。配置了多个项目或使用账户令牌模式时，可选填 project。

list-occurrences(counter, limit?, page?, last_id?, max_tokens?, project?)：查找 Rollbar 问题背后的实际发生记录，而不仅是问题摘要。传入问题的计数器，即可获取各条记录，每条记录都包含自己的时间戳、环境和错误详情。

使用 limit 控制返回的发生记录数量（默认为 3，最大为 100），并使用 page 或 last_id 翻阅更多记录。last_id 使用游标分页：传入上一批结果中最后一条发生记录的 id，即可获取其后的下一批记录。我们添加此功能，是因为如果发生记录在两次调用之间发生变化，普通的页码可能会跳过或重复结果，而 last_id 不会，因此翻阅大量发生记录时请使用它。如果两者都传入，则以 last_id 为准。每页中的发生记录始终按时间戳降序排列（最新的在前），因此你看到的最后一条记录，其 id 可可靠地作为 last_id 传回。

发生记录的数据很快就会变得很大，尤其是包含大型堆栈跟踪或请求负载的错误。max_tokens（默认为 20000，最小值为 100）会限制整个响应的大致大小，约为 max_tokens * 4 个字符。我们添加此限制，是因为如果不设上限，少量发生记录也可能远超对话所能容纳的内容。不过，你请求的每条发生记录仍会出现在响应中。为了控制在限制范围内，工具不会删掉任何记录，而是逐步缩减最大的一些记录，尽可能保留最有用的字段（级别、环境、异常消息等），最后才会仅保留 ID 和时间戳。顶层的 _truncation 字段会告知你是否发生了这种情况。如果你的 limit 和 max_tokens 确实无法容纳每条发生记录的最简版本，工具会明确报错，提示你降低 limit 或提高 max_tokens，而不会静默返回不完整的页面。

有些 Rollbar 问题实际上是多个问题组合而成的组。Rollbar 的公共 API 目前还无法正确列出这类组的问题发生记录，因此对组问题调用此工具时，会明确返回 group_item_not_supported 消息，而不是悄悄显示空列表，让人误以为该问题完全没有发生记录。

配置了多个项目时，可选填 project。示例提示词：显示问题 #24265 最近的 3 条发生记录

list-item-events(item_id?, counter?, type?, page?, limit?, project?)：按从早到晚的顺序读取问题历史，包括系统事件。必须且只能提供 Rollbar 中显示的全局 item_id 或项目本地 counter。page 默认为 1；limit 默认为 20，取值范围为 1–5000。结果格式为 { events, page, total_count }，其中计数反映筛选条件。空页面是有效结果。页面和事件详情会完整返回；如需缩小响应，请降低 limit。

将 type 设为以下任意值组成的数组，或省略它以包含所有可用类型：

类型	其他事件字段
item_comment	text、via_api
item_level_history	level
item_status_history	status、comment，以及可用的解决/部署详情
item_snooze_history	snooze_type、snooze_status、过期阈值
item_assigned_user_history	assigned_user_id
item_assigned_team_history	assigned_team_id
item_title_history	title、occurrence_id
item_group_history	action、item_counters、count
item_merge_history	action、group_item_counter

所有事件都包含 id、type、item_id、user_id、username 和 timestamp；作者字段可能为 null。排序顺序为时间戳、类型、ID，均按升序排列。不同事件类型可能具有相同的 ID；请使用 (type, id) 标识事件。解决备注会出现在 item_status_history.comment 中，因此查找解决上下文时请包含此类型。历史记录端点不支持游标、日期、文本或作者筛选。如果账号无法使用暂缓历史记录，则会省略该记录；此时明确请求暂缓历史记录会返回权限错误。

list-item-events 参数示例：

{ "project": "Backend", "counter": 42, "type": ["item_comment", "item_status_history"], "page": 1, "limit": 20 }

post-item-comment(item_id?, counter?, comment, project?)：以已连接用户的身份添加评论。必须且只能提供一种条目标识符，并提供非空的 comment 文本。此工具会返回已创建的评论，其中包含 id、type: "comment"、source: "comment"、item_id、user_id、username、timestamp、text 和 via_api: true。使用 list-item-events 并筛选为 item_comment 可读取此评论。

{ "project": "Backend", "counter": 42, "comment": "Investigated the regression; the fix is in PR #123." }

后端会将完整序列化的评论数据（包括作者元数据和 JSON 转义）限制在 65,535 字节以内。这不是字符数限制，也不是仅针对文本的字节数限制。MCP 会原样发送文本，并在后端报错时报告大小错误，而不会截断文本。发布失败后不会重试：结果不确定时，评论可能已经创建。重试前请检查历史记录。

这两个工具都会保留后端错误。常见错误包括参数无效（400/422）、身份验证失败（401）、范围/项目权限不足或暂缓历史记录不可用（403）、条目不属于所选项目或未找到（404），以及评论超出大小限制（413）。发布内容必须为 JSON（415）；工具会自动提供相应的内容类型。若未配置用户凭据，服务器会在发起任何 HTTP 调用前拒绝发布。

get-replay(environment, sessionId, replayId, delivery?, project?)：获取特定会话的会话回放元数据和载荷，以便查看用户在发生错误前的实际操作。

默认情况下（delivery="file"），回放 JSON 会写入磁盘上的临时文件，工具会返回文件路径。此方式适用于所有场景，但文件会一直保留，直到你自行清理。若改为设置 delivery="resource"，则会返回 MCP 感知型客户端可直接读取的 rollbar:// 链接，且不会留下文件；但这仅适用于服务器始终只与一个项目通信的情况（单项目令牌模式，或恰好配置了一个项目的账号令牌模式）。如果配置了多个项目，请使用 delivery="file" 并明确传入 project。

当配置了多个项目或处于账号令牌模式时，可选填 project。提示词示例：获取 staging 环境中会话 abc 的回放 789。

update-item(itemId, status?, level?, title?, assignedUserId?, resolvedInVersion?, snoozed?, teamId?, project?)：更改条目的状态、级别、标题、受指派人、解决版本、暂缓状态或所属团队，以便直接处理条目，而无需切换到 Rollbar 界面。

此操作需要写入权限：具有 write 范围的项目令牌，或同时具有 read 和 write 范围且符合用户权限的账号/用户令牌。只读令牌无法执行此操作。当配置了多个项目或处于账号令牌模式时，可选填 project。提示词示例：将 Rollbar 条目 #123456 标记为已解决，或 将条目 #123456 指派给用户 ID 789。

使用方法

Claude Code

按如下方式配置 .mcp.json。

使用环境变量（单个项目）：

{
  "mcpServers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
      }
    }
  }
}

也可以在 env 块中添加 ROLLBAR_API_BASE，以指定非生产环境的 API 端点。

使用账户访问令牌（账户下的每个项目都适用，无需为每个项目单独配置令牌）：

{
  "mcpServers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_ACCOUNT_ACCESS_TOKEN": "<account access token>"
      }
    }
  }
}

使用配置文件（单个或多个项目）：

{
  "mcpServers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"
      }
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.rollbar]
command = "npx"
args = ["-y", "@rollbar/mcp-server@latest"]
env = { "ROLLBAR_ACCESS_TOKEN" = "<project read/write access token>" }

或者使用配置文件：

[mcp_servers.rollbar]
command = "npx"
args = ["-y", "@rollbar/mcp-server@latest"]
env = { "ROLLBAR_CONFIG_FILE" = "/path/to/.rollbar-mcp.json" }

Junie

按如下方式配置 .junie/mcp/mcp.json（使用环境变量，或通过 ROLLBAR_CONFIG_FILE 指定配置文件）：

{
  "mcpServers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
      }
    }
  }
}

Cursor

配置 Cursor 的 MCP 服务（Cursor 设置 → 功能 → MCP，或在设置中搜索“MCP”）。可使用环境变量或配置文件。

使用环境变量（单个项目）：

{
  "mcpServers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
      }
    }
  }
}

使用配置文件（单个或多个项目）：

{
  "mcpServers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"
      }
    }
  }
}

更改 MCP 设置后，请重启 Cursor（或重新加载窗口）。如需使用本地构建版本而非 npx，请参阅 CONTRIBUTING.md。

VS Code（包括 GitHub Copilot）

按如下方式配置 .vscode/mcp.json（使用环境变量，或通过 ROLLBAR_CONFIG_FILE 指定配置文件）：

{
  "servers": {
    "rollbar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
      }
    }
  }
}

或者使用本地开发安装版本，请参阅 CONTRIBUTING.md。

这是 GitHub Copilot 在 VS Code 中的 Agent 模式读取的同一个文件。将其放在 .vscode/mcp.json 中，可与仓库中的所有人共享服务；也可以放在用户配置文件的 mcp.json 中（命令面板 → MCP: 打开用户配置），避免将令牌存入仓库。保存后，使用 MCP: 列出服务 → rollbar → 启动 启动服务，然后通过 Copilot Chat Agent 模式工具栏中的 🛠️ 图标选择工具。

GitHub Copilot CLI

添加到 ~/.copilot/mcp-config.json。请注意，Copilot CLI 使用 mcpServers（而不是 VS Code 的 servers），并将 stdio 传输方式写作 "type": "local"：

{
  "mcpServers": {
    "rollbar": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
      },
      "tools": ["*"]
    }
  }
}

或者使用配置文件，将 env 块替换为 ROLLBAR_CONFIG_FILE：

{
  "mcpServers": {
    "rollbar": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@rollbar/mcp-server@latest"],
      "env": {
        "ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"
      },
      "tools": ["*"]
    }
  }
}

tools: ["*"] 会启用所有 Rollbar 工具；如果希望显式选择工具，可以将其缩小为特定的工具名称。若要将服务限定于单个仓库，而不是整个账户，请将相同的 JSON 放在仓库根目录下的 .mcp.json 或 .github/mcp.json 中。Copilot CLI 只有在首次启动时确认文件夹信任后，才会加载项目级配置；项目定义的优先级高于 ~/.copilot/mcp-config.json。

在交互式会话中运行 /mcp（或在 shell 中运行 copilot mcp list），以确认服务已连接。