honeycomb-mcp-server

# Honeycomb MCP Server <a href="https://glama.ai/mcp/servers/honeycomb-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@kajirita2002/honeycomb-mcp-server/badge" alt="Honeycomb MCP server" /> </a> *Read this in [Japanese](README.ja.md)* ## Overview This server is an interface that uses the [Model Context Protocol (MCP)](https://github.com/anthropics/anthropic-cookbook/tree/main/model_context_protocol) to enable Claude AI to interact with the [Honeycomb API](https://docs.honeycomb.io/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 ```bash # Install globally npm install -g @kajirita2002/honeycomb-mcp-server # Or use directly with npx npx @kajirita2002/honeycomb-mcp-server ``` ### Setting Environment Variables ```bash # 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: ```json "honeycomb": { "command": "npx", "args": ["-y", "@kajirita2002/honeycomb-mcp-server"], "env": { "HONEYCOMB_API_KEY": "your_honeycomb_api_key" } } ``` ### Starting the Server ```bash # Start the server npm start ``` ## 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: ``` [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 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. ``` ## 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 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 ```bash git clone https://github.com/your-username/honeycomb-mcp-server.git ``` 3. Install dependencies ```bash npm install ``` 4. Make your changes 5. Run the build ```bash npm run build ``` 6. Test your changes locally ### Pull Request Process 1. Create a feature branch ```bash git checkout -b feat-your-feature-name ``` 2. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/) format ```bash git commit -m "feat: add new feature" ``` 3. Push to your fork ```bash 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](LICENSE) file for details.