honeybadger-mcp-server

# Honeybadger MCP Server

An MCP (Model Context Protocol) server for [Honeybadger](https://www.honeybadger.io), 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](https://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](https://mcp.honeybadger.io) instead (see above).

First, pull the Docker image:

```bash
docker pull ghcr.io/honeybadger-io/honeybadger-mcp-server:latest
```

Then, configure your MCP client(s). You can find your personal auth token under the "Authentication" tab in your [Honeybadger user settings](https://app.honeybadger.io/users/edit#authentication).

### Cursor, Windsurf, and Claude Desktop

Put this config in `~/.cursor/mcp.json` for [Cursor](https://docs.cursor.com/context/model-context-protocol), or `~/.codeium/windsurf/mcp_config.json` for [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp). See Anthropic's [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user) for how to locate your `claude_desktop_config.json` for Claude Desktop:

```json
{
  "mcpServers": {
    "honeybadger": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "HONEYBADGER_PERSONAL_AUTH_TOKEN",
        "ghcr.io/honeybadger-io/honeybadger-mcp-server"
      ],
      "env": {
        "HONEYBADGER_PERSONAL_AUTH_TOKEN": "your personal auth token"
      }
    }
  }
}
```

### Claude Code

Run this command to configure [Claude Code](https://www.anthropic.com/claude-code):

```bash
claude mcp add honeybadger -- docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN="HONEYBADGER_PERSONAL_AUTH_TOKEN" ghcr.io/honeybadger-io/honeybadger-mcp-server:latest
```

### VS Code

Add the following to your [user settings](https://code.visualstudio.com/docs/configure/settings#_settings-json-file) or `.vscode/mcp.json` in your workspace:

```json
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "honeybadger_auth_token",
        "description": "Honeybadger Personal Auth Token",
        "password": true
      }
    ],
    "servers": {
      "honeybadger": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "HONEYBADGER_PERSONAL_AUTH_TOKEN",
          "ghcr.io/honeybadger-io/honeybadger-mcp-server"
        ],
        "env": {
          "HONEYBADGER_PERSONAL_AUTH_TOKEN": "${input:honeybadger_auth_token}"
        }
      }
    }
  }
}
```

See [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.

### Zed

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

```json
{
  "context_servers": {
    "honeybadger": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "HONEYBADGER_PERSONAL_AUTH_TOKEN",
          "ghcr.io/honeybadger-io/honeybadger-mcp-server"
        ],
        "env": {
          "HONEYBADGER_PERSONAL_AUTH_TOKEN": "your personal auth token"
        }
      },
      "settings": {}
    }
  }
}
```

### Building Docker locally

To build the Docker image and run it locally:

```bash
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" with
"honeybadger-mcp-server" in any of the configs above. Or you can run the image
directly:

```bash
docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN honeybadger-mcp-server
```

### Building from source

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

```bash
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:

```json
{
  "mcpServers": {
    "honeybadger": {
      "command": "/path/to/honeybadger-mcp-server",
      "args": ["stdio"],
      "env": {
        "HONEYBADGER_PERSONAL_AUTH_TOKEN": "your personal auth token"
      }
    }
  }
}
```

## Configuration

### Environment Variables

| Environment Variable              | Required | Default                    | Description                                                             |
| --------------------------------- | -------- | -------------------------- | ----------------------------------------------------------------------- |
| `HONEYBADGER_PERSONAL_AUTH_TOKEN` | yes      | —                          | API token for Honeybadger                                               |
| `HONEYBADGER_READ_ONLY`           | no       | true                       | Run in read-only mode, excluding write operations like `delete_project` |
| `LOG_LEVEL`                       | no       | info                       | Log verbosity (debug, info, warn, error)                                |
| `HONEYBADGER_API_URL`             | no       | https://app.honeybadger.io | Override the base URL for Honeybadger's API                             |
| `HONEYBADGER_INSTRUCTIONS_URL`    | no       | https://docs.honeybadger.io/resources/llms/instructions | Override the base URL the LLM reference topics are fetched from |
| `MCP_CONFIRM_SECRET`              | HTTP mode only | —                    | Signs delete confirmation tokens. At least 32 characters, and identical on every instance behind a load balancer. The server won't start in HTTP mode without it; stdio mode doesn't use it |

**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](https://docs.honeybadger.io/resources/data-residency/), set `HONEYBADGER_API_URL` to `https://eu-app.honeybadger.io` and use a personal auth token from your [EU user settings](https://eu-app.honeybadger.io/users/edit#authentication). A US token won't authenticate against the EU region, and vice versa.

For example, with Claude Code:

```bash
claude mcp add honeybadger-eu -- docker run -i --rm -e HONEYBADGER_PERSONAL_AUTH_TOKEN="your_eu_token" -e HONEYBADGER_API_URL="https://eu-app.honeybadger.io" ghcr.io/honeybadger-io/honeybadger-mcp-server:latest
```

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:

```bash
# 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`:

```yaml
auth-token: "your_token_here"
log-level: "info"
api-url: "https://app.honeybadger.io"
read-only: true
```

## Tools

Delete tools (`delete_project`, `delete_dashboard`, `delete_alarm`, `delete_check_in`, `delete_fault_comment`) 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](https://docs.honeybadger.io/resources/llms/instructions/) 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
  - `account_