Betterstack Logs MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to query and analyze logs from Betterstack. Supports querying across multiple sources and source groups with intelligent source selection.

Features

• Multi-source querying: Query individual sources or source groups
• Source management: Discover and inspect available sources and groups
• Query tools: Execute structured ClickHouse SQL queries with intelligent filtering
• Historical data: Access both recent and archived logs
• AI-friendly: Intelligent source selection based on query context

Quick Start with NPX (Recommended)

The easiest way to use this MCP server is via NPX - no installation required!

1. Add to Claude Code Configuration

Add this to your Claude Code MCP configuration file:

{
  "mcpServers": {
    "betterstack": {
      "command": "npx",
      "args": ["-y", "@blaze-money/betterstack-logs-mcp"],
      "env": {
        "BETTERSTACK_API_TOKEN": "your-api-token-here",
        "BETTERSTACK_CLICKHOUSE_USERNAME": "your-clickhouse-username",
        "BETTERSTACK_CLICKHOUSE_PASSWORD": "your-clickhouse-password",
        "BETTERSTACK_CLICKHOUSE_QUERY_ENDPOINT": "your-clickhouse-endpoint"
      }
    }
  }
}

2. Get Your Credentials

• API Token: Get from BetterStack API settings
• ClickHouse credentials: Available in your BetterStack team settings under "Log destinations"

3. Restart Claude

Restart Claude Code to load the new MCP server. The server will be automatically downloaded and started via NPX.

Local Development Installation

If you want to develop or modify the server locally:

1. Clone this repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Configure environment variables (see Configuration section)

Configuration

Environment Variables

Betterstack requires two different authentication methods:

Copy .env.example to .env and configure:

# ClickHouse Database Credentials (for log queries)
BETTERSTACK_CLICKHOUSE_USERNAME=your_clickhouse_username
BETTERSTACK_CLICKHOUSE_PASSWORD=your_clickhouse_password
BETTERSTACK_CLICKHOUSE_QUERY_ENDPOINT=your_clickhouse_endpoint_url

# API Token (for source management)
BETTERSTACK_API_TOKEN=your_api_token_from_betterstack_dashboard

# Optional
BETTERSTACK_DEFAULT_SOURCE_GROUP=production

Getting Your Credentials:

1. ClickHouse Credentials (for log queries):

   • In Betterstack dashboard: Dashboards → Connect remotely → Create connection
   • Save the generated username, password, and endpoint URL

2. API Token (for source management):

   • Go to Betterstack API Tokens
   • Select your team
   • Create or copy an existing Telemetry API token

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "betterstack": {
      "command": "npx",
      "args": ["-y", "@blaze-money/betterstack-logs-mcp"],
      "env": {
        "BETTERSTACK_CLICKHOUSE_USERNAME": "your_clickhouse_username",
        "BETTERSTACK_CLICKHOUSE_PASSWORD": "your_clickhouse_password",
        "BETTERSTACK_CLICKHOUSE_QUERY_ENDPOINT": "your_clickhouse_endpoint_url",
        "BETTERSTACK_API_TOKEN": "your_api_token_here",
        "BETTERSTACK_DEFAULT_SOURCE_GROUP": "production"
      }
    }
  }
}

Available Tools

Source Management

• list_sources: Get all available log sources
• list_source_groups: Get configured source groups
• get_source_info: Get details about a specific source
• get_source_group_info: Get details about a source group

Query Tools

• query_logs: Execute structured log queries with filtering and time range support
• debug_table_info: Inspect source table schemas and query generation

Usage Examples

# List available sources
AI: What sources do we have?

# Query recent logs with filtering
AI: Show me ERROR level logs from the last hour in production

# Query specific time range
AI: Show me all logs from yesterday between 2pm and 4pm

# Get source group details
AI: What's included in our production source group?

Development

npm run dev    # Watch mode
npm run build  # Build for production

License

MIT