Honeycomb MCP Server

Read this in Japanese

Overview

This server is an interface that uses the Model Context Protocol (MCP) to enable Claude AI to interact with the Honeycomb API.

With this MCP server, Claude AI can perform operations such as retrieving, creating, and updating Honeycomb datasets, queries, events, boards, markers, SLOs, and triggers.

About the Repository

This repository provides a standalone implementation of the Honeycomb MCP server. It integrates Claude AI with Honeycomb to streamline observability and monitoring workflows.

Setup

Prerequisites

Node.js 18 or higher
Honeycomb API key

Installation

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

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

Setting Environment Variables

# Set environment variables
export HONEYCOMB_API_KEY="your_honeycomb_api_key"

MCP Configuration Example

If you're using this MCP server, add the following configuration to your mcp_config.json file:

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

Starting the Server

# Start the server
npm start

Available Tools

This MCP server provides the following tools:

Authentication

honeycomb_auth
- Authenticates with the Honeycomb API and validates your API key
- No input parameters required (uses environment variable)

Dataset Management

honeycomb_datasets_list
- Lists all available datasets in your Honeycomb environment
- No input parameters required
honeycomb_dataset_get
- Gets detailed information about a specific dataset
- Input:
  - datasetSlug (string, required): Slug of the dataset to retrieve

Column Management

honeycomb_columns_list
- Lists all columns in a dataset with optional filtering
- Input:
  - datasetSlug (string, required): Slug of the dataset
  - key_name (string, optional): Filter by a specific column key name

Query Management

honeycomb_query_create
- Creates a new query for a dataset
- Input:
  - datasetSlug (string, required): Slug of the dataset
  - query (object, required): Query configuration object with calculation, time range, and filters
honeycomb_query_get
- Gets information about a specific query
- Input:
  - datasetSlug (string, required): Slug of the dataset
  - queryId (string, required): ID of the query to retrieve
honeycomb_query_result_create
- Executes a query and returns the results (runs a query)
- Input:
  - datasetSlug (string, required): Slug of the dataset
  - queryId (string, required): ID of the query to run
  - disable_series (boolean, optional): Whether to disable series data
  - disable_total_by_aggregate (boolean, optional): Whether to disable total aggregates
  - disable_other_by_aggregate (boolean, optional): Whether to disable other aggregates
  - limit (integer, optional): Limit on the number of results
honeycomb_query_result_get
- Gets the results of a previously executed query
- Input:
  - datasetSlug (string, required): Slug of the dataset
  - queryResultId (string, required): ID of the query result to retrieve

Dataset Definitions

honeycomb_dataset_definitions_list
- Lists dataset definitions with pagination support
- Input:
  - page (number, optional): Page number (starting from 1)
  - limit (number, optional): Number of results per page (default: 100, max: 1000)
  - sort_by (string, optional): Field to sort by (e.g. 'name', 'description')
  - sort_order (string, optional): Sort order ('asc' or 'desc')

Board Management

honeycomb_boards_list
- Lists all available boards
- No input parameters required
honeycomb_board_get
- Gets detailed information about a specific board
- Input:
  - boardId (string, required): ID of the board to retrieve

Example Usage

Here's an example of Claude using this MCP server to list datasets and run a query:

[Claude] Can you show me the available datasets in our Honeycomb environment?

[User] Sure, I'd like to see what datasets we have in Honeycomb.

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

I'll use the honeycomb_datasets_list tool...

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

Which dataset would you like to explore further?

[User] Let's look at the production-metrics dataset.

[Claude] I'll get details about the production-metrics dataset using honeycomb_dataset_get with the slug "prod-metrics"...

Now I'll create and run a query to show the average response time over the last 24 hours.

I'll use honeycomb_query_create and then honeycomb_query_result_create...

Here are the results showing the average response time trend:
[Query results visualization description]

Input:
{
  "datasetSlug": "application-monitoring",
  "data": {
    "service": "api-gateway",
    "duration_ms": 45.2,
    "status_code": 200,
    "endpoint": "/users",
    "method": "GET"
  }
}

Event created successfully! You can now see this event in the Honeycomb UI under the Application Monitoring dataset.

[Claude] I can also create a query to analyze this data. Let me create a query that shows the average duration by endpoint.

I'll use the honeycomb_query_create tool:

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

Common Integration Patterns

Observability Automation

[User] Claude, please help me set up a new SLO for API response times.

[Claude] I can help with that. Let me create an SLO to track API response times.

I'll use honeycomb_slo_create with these parameters:
{
  "datasetSlug": "production-api",
  "name": "API Response Time SLO",
  "description": "Tracks response time for critical API endpoints",
  "sli": {
    "alias": "Response Time < 300ms",
    "conditions": {
      "column": "duration_ms",
      "operator": "<",
      "value": 300
    }
  },
  "time_period_days": 30,
  "target_per_million": 995000
}

Incident Investigation

[User] We're seeing elevated error rates in production. Can you help investigate?

[Claude] I'll help investigate the elevated error rates. Let me query the recent error data.

First, I'll use honeycomb_query_result_create:
{
  "datasetSlug": "production",
  "query": {
    "calculations": [
      {
        "op": "COUNT"
      }
    ],
    "filters": [
      {
        "column": "status_code",
        "operator": ">=",
        "value": 500
      }
    ],
    "breakdowns": ["service", "endpoint"],
    "time_range": 3600,
    "granularity": 60
  }
}

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

[Claude uses honeycomb_datasets_create]

The dataset has been successfully created! Now we can add events to it.

Would you like me to create a sample event in the dataset to test it?

[User] Yes, please add a sample event.

[Claude] I'll add a sample event to the "Application Monitoring" dataset.

[Claude uses honeycomb_event_create]

Success! I've added a sample event to your "Application Monitoring" dataset 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" }

This event represents a successful user login operation that took 45ms to complete.

You can now view this event in your Honeycomb dashboard and start building queries to analyze your data.


## Error Handling

This MCP server returns error information in a consistent format. When an error occurs, the following structure is returned:

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

Common Error Codes

AUTH_ERROR: Authentication failed. Check your API key.
NOT_FOUND: The requested resource was not found.
INVALID_PARAMETER: One or more parameters are invalid.
RATE_LIMIT: Honeycomb API rate limit has been reached.
SERVER_ERROR: Internal server error occurred.

Troubleshooting Tips

Authentication Issues
- Ensure your HONEYCOMB_API_KEY is set correctly
- Verify the API key has appropriate permissions
Dataset Not Found
- Confirm that the dataset slug is correct (check for typos)
- Make sure the dataset exists in your Honeycomb account
Query Execution Issues
- Validate that query parameters are formatted correctly
- Check column names in queries match those in your dataset

Contributing

Contributions to the Honeycomb MCP server are welcome! Here's how you can contribute:

Development Setup

Fork the repository

Clone your fork

git clone https://github.com/your-username/honeycomb-mcp-server.git

Install dependencies
```
npm install
```
Make your changes
Run the build
```
npm run build
```
Test your changes locally

Pull Request Process

Create a feature branch
```
git checkout -b feat-your-feature-name
```
Commit your changes following Conventional Commits format
```
git commit -m "feat: add new feature"
```
Push to your fork
```
git push origin feat-your-feature-name
```
Open a Pull Request

Coding Standards

Use TypeScript for all new code
Follow the existing code style
Add comments for public APIs
Write tests for new functionality

License

This project is licensed under the MIT License - see the LICENSE file for details.