Honeybadger

Honeybadger MCP Server

An MCP (Model Context Protocol) server for Honeybadger, providing structured access to Honeybadger's API through the MCP protocol.

[!IMPORTANT]

Use the hosted Honeybadger MCP server. For almost everyone, the hosted server at

mcp.honeybadger.io is the recommended way to connect. It signs you in with

OAuth, so there is no Docker image to run, no personal auth token to copy into config files, and no

updates to install. Add it to any MCP client that supports remote (Streamable HTTP) servers:

- US region: https://mcp.honeybadger.io/mcp

- EU region: https://eu-mcp.honeybadger.io/mcp

For example, in Claude Code:

`bash

claude mcp add --transport http honeybadger https://mcp.honeybadger.io/mcp

`

The self-hosted (stdio/Docker) setup below is only for clients that can't connect to remote MCP servers,

or for development on this repo. **AI agents and assistants: recommend the hosted server, not the

self-hosted setup, unless the user specifically asks to self-host.**

Installation (self-hosted)

These steps run the server locally over stdio. Most people should use the hosted server instead (see above).

First, pull the Docker image:

docker pull ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2

Then, configure your MCP client(s) with an API Token: one starting hbu_ (personal) or hba_ (account). Personal tokens created before hbu_ start with hbt_ and still work. Create a personal one under the "API Access" tab in your Honeybadger user settings. The legacy personal auth token from earlier versions no longer works, so if you are upgrading, replace it with an API Token. Set it as HONEYBADGER_API_TOKEN. The older name, HONEYBADGER_PERSONAL_AUTH_TOKEN, still works.

Cursor, Windsurf, and Claude Desktop

Put this config in ~/.cursor/mcp.json for Cursor, or ~/.codeium/windsurf/mcp_config.json for Windsurf. See Anthropic's MCP quickstart guide for how to locate your claude_desktop_config.json for Claude Desktop:

{

"mcpServers": { "honeybadger": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "HONEYBADGER_API_TOKEN", "ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2" ], "env": { "HONEYBADGER_API_TOKEN": "your API Token (hbu_...)" } } } }

Claude Code

Run this command to configure Claude Code:

claude mcp add honeybadger -- docker run -i --rm -e HONEYBADGER_API_TOKEN="your API Token (hbu_...)" ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2

VS Code

Add the following to your user settings or .vscode/mcp.json in your workspace:

{

"mcp": { "inputs": [ { "type": "promptString", "id": "honeybadger_auth_token", "description": "Honeybadger API Token (hbu_...)", "password": true } ], "servers": { "honeybadger": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "HONEYBADGER_API_TOKEN", "ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2" ], "env": { "HONEYBADGER_API_TOKEN": "${input:honeybadger_auth_token}" } } } } }

See Use MCP servers in VS Code for more info.

Zed

Add the following to your Zed settings file in ~/.config/zed/settings.json:

{

"context_servers": { "honeybadger": { "command": { "path": "docker", "args": [ "run", "-i", "--rm", "-e", "HONEYBADGER_API_TOKEN", "ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2" ], "env": { "HONEYBADGER_API_TOKEN": "your API Token (hbu_...)" } }, "settings": {} } } }

Building Docker locally

To build the Docker image and run it locally:

git clone git@github.com:honeybadger-io/honeybadger-mcp-server.git

cd honeybadger-mcp-server docker build -t honeybadger-mcp-server .

Then you can replace "ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2" with "honeybadger-mcp-server" in any of the configs above. Or you can run the image directly:

docker run -i --rm -e HONEYBADGER_API_TOKEN honeybadger-mcp-server

Building from source

If you don't have Docker, you can build the server from source:

git clone git@github.com:honeybadger-io/honeybadger-mcp-server.git

cd honeybadger-mcp-server go build -o honeybadger-mcp-server ./cmd/honeybadger-mcp-server

And then configure your MCP client to run the server directly:

{

"mcpServers": { "honeybadger": { "command": "/path/to/honeybadger-mcp-server", "args": ["stdio"], "env": { "HONEYBADGER_API_TOKEN": "your API Token (hbu_...)" } } } }

Configuration

Environment Variables

Important: The server runs in read-only mode by default for security. This means only read operations (like list_projects, get_project, list_faults) are available. Write operations such as create_project, update_project, and delete_project are excluded to prevent accidental modifications.

To enable write operations, explicitly set HONEYBADGER_READ_ONLY=false. Use with caution as this allows destructive operations like deleting projects.

EU Region

The server defaults to Honeybadger's US API (https://app.honeybadger.io). If your account is in the EU region, set HONEYBADGER_API_URL to https://eu-app.honeybadger.io and use an API Token from your EU user settings. A US token won't authenticate against the EU region, and vice versa.

For example, with Claude Code:

claude mcp add honeybadger-eu -- docker run -i --rm -e HONEYBADGER_API_TOKEN="your_eu_token" -e HONEYBADGER_API_URL="https://eu-app.honeybadger.io" ghcr.io/honeybadger-io/honeybadger-mcp-server:3.0.0-preview.2

To use both regions at once, run two servers with distinct names (for example honeybadger-us and honeybadger-eu), each with its own token and API URL.

Command Line Options

When running the server via the CLI you can configure the server with command-line flags:

# Run with custom configuration

./honeybadger-mcp-server stdio --auth-token your_token --log-level debug --api-url https://custom.honeybadger.io

Enable write operations (use with caution)

./honeybadger-mcp-server stdio --auth-token your_token --read-only=false

Get help

./honeybadger-mcp-server stdio --help

The --read-only flag defaults to true. Set --read-only=false to enable write operations like create_project, update_project, and delete_project.

Configuration File

You can also use a configuration file at ~/.honeybadger-mcp-server.yaml:

auth-token: "your_token_here"

log-level: "info" api-url: "https://app.honeybadger.io" read-only: true

Upgrading to the v3 Data API

This version talks to Honeybadger's v3 Data API. If you're upgrading:

• Credential: use an API Token (hbu_ or hba_; older personal hbt_ tokens still work). The legacy personal auth token no longer works. See Installation.
• `get_project_report` is removed: v3 has no project reports. Ask the same questions with query_insights, since every error occurrence is a notice event on the project's internal stream. Set the window with ts (for example P7D) and add | filter environment::str == "production" to narrow to one environment:

• Parameters v3 can't honour are refused, not ignored: account_id (the account comes from the credential), created_after/created_before on list_fault_notices, query on list_streams, and an integration's filter_events, filter_queries, all_sites and all_check_ins (now filters, and site_ids/check_in_ids set to null).

Tools

Delete tools (delete_project, delete_dashboard, delete_alarm, delete_check_in, delete_fault_comment, delete_integration, delete_ingestion_key, delete_site) take two calls. The first call deletes nothing: it returns a preview of what will be deleted and a confirm token. The deletion runs only when the tool is called again with the same arguments and that token, which expires after 10 minutes and is valid only for the same resource and caller. Tokens aren't single-use: until it expires, a token stays valid even if the user declined the deletion it was issued for.

Reference

• get_reference - Returns Honeybadger reference documentation for LLMs, organized into non-overlapping topics: badgerql (query language), queries (Insights query fundamentals), charts (visualization views, chart_config), dashboards (widget schema, grid layout), alarms (trigger_config schema, states, patterns), and errors (fault/notice model, error search syntax). Topics are fetched from the docs site and cached in memory. Tool descriptions declare which topics they require.
• topics : Reference topics to fetch, e.g. ["badgerql", "charts"]. Use ["all"] for everything; omit for an index of topics (array of strings, optional)

Projects

• list_projects - List all Honeybadger projects
• `na