Honeycomb MCP server for AI agents

This MCP server provides a bridge between Claude AI and the Honeycomb API, enabling you to interact with Honeycomb for observability and monitoring workflows directly through Claude.

Installation and Setup

Prerequisites

Node.js 18 or higher
Honeycomb API key

Installation

You can install the server globally or use it directly with npx:

# Install globally
npm install -g @kajirita2002/honeycomb-mcp-server

# Or use directly with npx
npx @kajirita2002/honeycomb-mcp-server

Configuration

Set up your Honeycomb API key as an environment variable:

export HONEYCOMB_API_KEY="your_honeycomb_api_key"

MCP Configuration

Add the following to your mcp_config.json file to configure Claude to use this server:

"honeycomb": {
  "command": "npx",
  "args": ["-y", "@kajirita2002/honeycomb-mcp-server"],
  "env": {
    "HONEYCOMB_API_KEY": "your_honeycomb_api_key"
  }
}

Starting the Server

Start the server with:

npm start

Available Tools

Authentication

honeycomb_auth: Authenticates with the Honeycomb API using your API key

Dataset Management

honeycomb_datasets_list: Lists all available datasets in your Honeycomb environment
honeycomb_dataset_get: Gets detailed information about a specific dataset

Column Management

honeycomb_columns_list: Lists all columns in a dataset with optional filtering

Query Management

honeycomb_query_create: Creates a new query for a dataset
honeycomb_query_get: Gets information about a specific query
honeycomb_query_result_create: Executes a query and returns the results
honeycomb_query_result_get: Gets the results of a previously executed query

Dataset Definitions

honeycomb_dataset_definitions_list: Lists dataset definitions with pagination support

Board Management

honeycomb_boards_list: Lists all available boards
honeycomb_board_get: Gets detailed information about a specific board

Usage Examples

Listing Datasets

When asking Claude to list your Honeycomb datasets:

[Claude] I'll list all the available datasets in your Honeycomb environment.

Here are your available datasets:
- production-metrics (slug: prod-metrics)
- staging-services (slug: staging-svc)
- application-logs (slug: app-logs)

Creating and Querying Data

Example of creating a dataset and adding an event:

[Claude] Creating dataset "Application Monitoring" with the description "Monitoring for our production application"...

The dataset has been successfully created! Now I'll add a sample event to it.

Success! I've added a sample event with the following data:
{
  "service": "api-server",
  "message": "User login successful",
  "duration_ms": 45,
  "status_code": 200,
  "endpoint": "/api/login",
  "timestamp": "2025-03-25T14:30:00Z"
}

Example of creating and running a query:

[Claude] I'll create a query that shows the average duration by endpoint:

Input:
{
  "datasetSlug": "application-monitoring",
  "query": {
    "calculations": [
      {
        "op": "AVG",
        "column": "duration_ms"
      }
    ],
    "breakdowns": ["endpoint"],
    "time_range": 3600
  }
}

Error Handling

When errors occur, the MCP server returns information in this format:

{
  "error": {
    "message": "Detailed error description",
    "code": "ERROR_CODE"
  }
}

Common Error Codes

AUTH_ERROR: Authentication failed
NOT_FOUND: Resource not found
INVALID_PARAMETER: Invalid parameters
RATE_LIMIT: API rate limit reached
SERVER_ERROR: Internal server error

Troubleshooting Tips

Authentication Issues: Verify your API key is correct and has appropriate permissions
Dataset Not Found: Check for typos in dataset slugs
Query Execution Issues: Ensure query parameters are properly formatted

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "honeycomb" '{"command":"npx","args":["-y","@kajirita2002/honeycomb-mcp-server"],"env":{"HONEYCOMB_API_KEY":"your_honeycomb_api_key"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "honeycomb": {
            "command": "npx",
            "args": [
                "-y",
                "@kajirita2002/honeycomb-mcp-server"
            ],
            "env": {
                "HONEYCOMB_API_KEY": "your_honeycomb_api_key"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "honeycomb": {
            "command": "npx",
            "args": [
                "-y",
                "@kajirita2002/honeycomb-mcp-server"
            ],
            "env": {
                "HONEYCOMB_API_KEY": "your_honeycomb_api_key"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect