Honeycomb MCP Server

Read this in

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.

Related MCP server: mcp-server-docker

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

Setting Environment Variables

MCP Configuration Example

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

Starting the Server

Available Tools

This MCP server provides the following tools:

Authentication

1. honeycomb_auth

   • Authenticates with the Honeycomb API and validates your API key

   • No input parameters required (uses environment variable)

Dataset Management

1. honeycomb_datasets_list

   • Lists all available datasets in your Honeycomb environment

   • No input parameters required

2. honeycomb_dataset_get

   • Gets detailed information about a specific dataset

   • Input:

     • datasetSlug (string, required): Slug of the dataset to retrieve

Column Management

1. 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

1. 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

2. 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

3. 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

4. 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

1. 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

1. honeycomb_boards_list

   • Lists all available boards

   • No input parameters required

2. 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:

Common Integration Patterns

1. 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 }

2. 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.

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

1. Authentication Issues

   • Ensure your HONEYCOMB_API_KEY is set correctly

   • Verify the API key has appropriate permissions

2. Dataset Not Found

   • Confirm that the dataset slug is correct (check for typos)

   • Make sure the dataset exists in your Honeycomb account

3. 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

1. Fork the repository

2. Clone your fork

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

3. Install dependencies

   npm install

4. Make your changes

5. Run the build

   npm run build

6. Test your changes locally

Pull Request Process

1. Create a feature branch

   git checkout -b feat-your-feature-name

2. Commit your changes following Conventional Commits format

   git commit -m "feat: add new feature"

3. Push to your fork

   git push origin feat-your-feature-name

4. 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.