# Loggerhead

> Loggerhead is a freemium MCP server for developer tools. Let a coding agent read the logs, metrics and traces of the app running on your Mac. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Freemium
- **Platforms:** macOS, CLI
- **Website:** https://getloggerhead.com
- **Repository:** https://github.com/rubics-code/loggerhead-mcp
- **MCP Registry name:** com.getloggerhead/loggerhead
- **Categories:** developer tools
- **Listing updated:** 2026-11-15

## About

Loggerhead is a native macOS app that receives OpenTelemetry data from software on your own machine and stores it in a local DuckDB file. This MCP bridge connects a coding agent to that store, so when a local endpoint returns errors the agent can search the logs, open the matching trace and see which span timed out before it proposes a fix. The app hosts the endpoint on loopback only, nothing leaves the Mac, and the app must be installed and running or the bridge exits.

Beyond reading telemetry, seven tools change a workspace's lint rules, each with a reason the user sees and can undo in the app, and one marks a lint finding fixed after a code change. The lint findings cover things like noisy logs, unbounded labels, secrets and lost trace context. Telemetry can be pushed in over OTLP from Docker, Kubernetes, another Mac or an app's SDK, or pulled from a Prometheus metrics URL.

It installs as a Claude Desktop extension bundle or a stdio command for Claude Code, Cursor, Codex and Windsurf. The app needs macOS 15 or later and the README says the free tier includes the MCP server.

## Features

- **Log search:** Query logs by text, severity and time.
- **Trace inspection:** Find traces by service, operation or duration and read every span.
- **Metric queries:** Read time-series metrics by name and range.
- **Telemetry linting:** List findings such as noisy logs, secrets and lost trace context.
- **Reversible rule changes:** Adjust lint rules with a stated reason the user can undo.
- **Local only:** Endpoint binds to 127.0.0.1 and data stays on the Mac.

## Good for

- Ask an agent to explain a local 500 error using real logs
- Trace a slow request through its spans
- Check what a service logged just before a failure
- Clean up noisy telemetry before shipping to production
- Mark a lint finding fixed after a code change

## Install

### Claude Code (Terminal)

```sh
claude mcp add loggerhead -- npx -y https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "loggerhead": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "loggerhead": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "loggerhead": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "loggerhead": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "loggerhead": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb"
      ]
    }
  }
}
```

## Tools

- `query_logs`: Search log records by text, severity and time.
- `query_metrics`: Read time-series metrics by name and time range.
- `query_traces`: Find traces by service, operation, duration and time.
- `get_trace`: Read every span of one trace.
- `list_environments`: List every workspace and environment with receiver ports.
- `get_receiver_info`: Report effective OTLP ports and addresses.
- `query_improvements`: List telemetry-lint findings.
- `list_lint_rules`: List lint rules of a workspace with state and thresholds.
- `query_ai_findings`: List findings of the last AI analysis run.
- `set_lint_rule_enabled`: Switch a lint rule on or off, with a reason.
- `set_lint_threshold`: Set a lint rule threshold, with a reason.
- `reset_lint_threshold`: Restore a threshold to default, with a reason.
- `add_lint_exception`: Hide findings of a rule for a service, metric, attribute, operation or message.
- `remove_lint_exception`: Remove a lint rule exception.
- `ignore_finding`: Ignore one lint finding by id.
- `unignore_finding`: Stop ignoring a lint finding.
- `mark_finding_fixed`: Mark a finding fixed after a code change.

## FAQ

### Does any data leave my Mac?

The README and site say the endpoint is loopback only and nothing leaves the machine.

### Does the app need to be running?

Yes. The bridge exits when the Loggerhead app is not running.

### Which clients can connect?

Claude Desktop via an extension bundle, plus Claude Code, Cursor, Codex, Windsurf and other stdio clients.

### Is it free?

The README says the free tier includes the MCP server; the site says the app is free to start.

### Which systems does it run on?

macOS 15 or later, Apple silicon and Intel.

### Is Loggerhead free?

Loggerhead has a free plan, with paid plans for more usage or features.

### How do I add Loggerhead to Claude Code?

Run this command in your terminal: claude mcp add loggerhead -- npx -y https://github.com/rubics-code/loggerhead-mcp/releases/download/v1.12.0/loggerhead-mcp.mcpb

### What are the best alternatives to Loggerhead?

The closest alternatives to Loggerhead are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/loggerhead
