Loggerhead MCP server
Commit Oct 13, 2026Allows an AI coding agent to read and query application logs, metrics, and traces stored in the Loggerhead Mac app.
Also known as rubics-code/loggerhead-mcp, loggerhead-mcp
- Stars
- 0
- Tools
- 17
- Downloads, 30 days
- —
- Latest version
- 1.12.0
- Last commit
- Oct 13, 2026
- License
- MIT
What is Loggerhead MCP?
Loggerhead allows an AI coding agent to read and query application logs, metrics, and traces stored in the Loggerhead Mac app. It exposes 17 tools, such as query_logs, query_metrics, query_traces.
Summary generated from the project's README
About Loggerhead MCP server
Loggerhead provides a bridge between your local telemetry data and AI coding agents. It connects the Loggerhead Mac app to MCP clients like Claude Desktop, Cursor, Windsurf, and Claude Code. This setup allows an agent to access OpenTelemetry logs, metrics, and traces that are stored in a local DuckDB file on your machine. Because the server runs on the loopback address, your data stays on your Mac and does not leave the device.
Developers use this server to let their AI assistants inspect application performance and debug issues directly from telemetry. The server includes tools to query logs by severity, search time-series metrics, and examine specific traces. It also features specialized tools for managing telemetry-lint findings, such as noisy logs or secrets. You can use these tools to enable or disable lint rules, adjust thresholds, and mark specific findings as fixed after you have applied code changes.
What you can do with it
- 1Debug application errorsAsk the AI to search through recent log records for specific error messages or high severity events.
- 2Analyze performance bottlenecksRequest a detailed breakdown of every span within a specific trace to find slow operations.
- 3Manage telemetry linting rulesInstruct the agent to change the threshold for a specific lint rule in your workspace.
- 4Verify bug fixesTell the AI to mark a telemetry finding as fixed after you have updated the code.
Written from the project's README. Every use case is checked against a quote from it.
Loggerhead MCP tools 17
Detected from the READMEquery_logsquery_metricsquery_tracesget_tracelist_environmentsget_receiver_infoquery_improvementslist_lint_rulesquery_ai_findingsset_lint_rule_enabledset_lint_thresholdreset_lint_threshold
| query_logs | — | |
| query_metrics | — | |
| query_traces | — | |
| get_trace | — | |
| list_environments | — | |
| get_receiver_info | — | |
| query_improvements | — | |
| list_lint_rules | — | |
| query_ai_findings | — | |
| set_lint_rule_enabled | — | |
| set_lint_threshold | — | |
| reset_lint_threshold | — |
Show all 17 toolsShow fewer tools
add_lint_exceptionremove_lint_exceptionignore_findingunignore_findingmark_finding_fixed
| add_lint_exception | — | |
| remove_lint_exception | — | |
| ignore_finding | — | |
| unignore_finding | — | |
| mark_finding_fixed | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablerubics-code/loggerhead-mcp is public and reachablegithub.com/rubics-code/loggerhead-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-13github.com/rubics-code/loggerhead-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model17 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubLoggerhead MCP server
Your coding agent reads your app's logs, metrics, and traces.
Loggerhead is a native Mac app that receives OpenTelemetry logs, metrics, and traces from the software you run on your own Mac, and stores them in a DuckDB file on your disk. The MCP server runs inside the app. This repository holds loggerhead-mcp, the small bridge that connects Claude, Cursor, Codex, Windsurf, or any other MCP client to it.
The tools read the telemetry. Seven tools change the lint rules of a workspace, each with a reason that the user sees and can undo in the app. One tool marks a finding fixed after a code change. The endpoint listens on loopback only. Nothing leaves the Mac.
The Loggerhead app must be installed and running. Download it first. The bridge exits when the app is not running. The free tier includes the MCP server.
Install
Claude Desktop
Download loggerhead-mcp.mcpb from the latest release and open it. Claude Desktop installs the extension.
Claude Code
claude mcp add loggerhead -- "/Applications/Loggerhead.app/Contents/Resources/loggerhead-mcp"
Cursor, Codex, Windsurf, and other stdio clients
Every stdio client takes the same two values. The .mcp.json in this repository is the file to copy:
{
"mcpServers": {
"loggerhead": {
"command": "/Applications/Loggerhead.app/Contents/Resources/loggerhead-mcp"
}
}
}
The app itself writes this entry for you: open Settings › AI and click Add beside your tool.
The bridge finds the app by itself on a fixed ladder of local ports. You set no port, and it needs no permission to read the app's files. Full instructions: Set up the MCP server.
Tools
| Tool | Purpose |
|---|---|
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 on this Mac, with the receiver ports. |
get_receiver_info |
Report the effective OTLP ports and the addresses to send telemetry to. |
query_improvements |
List the telemetry-lint findings: noisy logs, unbounded labels, secrets, lost trace context. |
list_lint_rules |
List the lint rules of a workspace with their state, thresholds, exceptions, ignored findings, and recent changes. |
query_ai_findings |
List the findings of the last AI analysis run. It does not start a run. |
set_lint_rule_enabled |
Switch a lint rule on or off for a workspace, with a reason. |
set_lint_threshold |
Set one threshold of a lint rule for a workspace, with a reason. |
reset_lint_threshold |
Put one threshold of a lint rule back to its default, with a reason. |
add_lint_exception |
Hide the findings of one lint rule for a service, metric, attribute key, operation, or log message, with a reason. |
remove_lint_exception |
Remove one lint rule exception, with a reason. |
ignore_finding |
Ignore one lint finding by its id, with a reason. |
unignore_finding |
Stop the ignore of one lint finding, with a reason. |
mark_finding_fixed |
Mark one lint finding fixed after a code change, so the app judges it by the telemetry after the fix. |
One resource, loggerhead://stats, reports the total counts of logs, metrics, and spans. Every parameter is in the tools reference.
Privacy Policy
The bridge and the server read telemetry from the Loggerhead app on the same Mac and hand it to the MCP client you connected. They collect nothing about you, they store nothing of their own, they share nothing with a third party, and they open no network connection except to 127.0.0.1. Data retention is the app's: the telemetry lives in a DuckDB file on your disk for as long as the app's retention setting keeps it, and you can delete the file. The full policy of the publisher, Rubics Code, is at https://getloggerhead.com/privacy. Contact: support@getloggerhead.com.
Registry
The registry name of this server is com.getloggerhead/loggerhead.
- MCP Registry name:
mcp-name: com.getloggerhead/loggerhead
Licence
The loggerhead-mcp bridge and the files in this repository are under the MIT licence.
The bridge contains open-source Swift packages. The .mcpb bundle has Acknowledgements.txt with the licence text and the notice text of each package.
The bridge connects to Loggerhead, a proprietary Mac app by Rubics Code (ABN 40 440 756 434), Australia. The app has a free tier, and the source of the app is not public. The Loggerhead terms of service apply to the app.
Loggerhead MCP questions
What tools does Loggerhead MCP provide?
It exposes 17 tools, including query_logs, query_metrics, query_traces, get_trace, list_environments.
Do I need to install anything else to use this?
Yes, the Loggerhead Mac app must be installed and running for the MCP server to function.
Is my data sent to the cloud?
No, the server only listens on loopback and nothing leaves your Mac.
How does the server connect to the app?
The bridge automatically finds the app using a fixed ladder of local ports.
Can I change linting rules through the AI?
Yes, there are tools available to enable/disable lint rules, set thresholds, and add exceptions.