Git Telemetry MCP

An MCP server implementing the documented, focused subset of the MCP 2026-07-28 protocol. It provides a Development Time Machine by analyzing git reflogs, commit history, working directory deltas, and permitted shell history to give AI assistants temporal context.

Quick Start

# Install dependencies
uv sync

# Run the MCP server (HTTP JSON-RPC on http://127.0.0.1:8787/mcp, SSE on /sse)
uv run git-telemetry-mcp

# Run tests
uv run pytest

MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop, Cursor, OpenCode):

{
  "mcpServers": {
    "git-telemetry": {
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}

HTTP security boundaries

The HTTP JSON-RPC endpoint is POST /mcp; the server also exposes the SSE stream at GET /sse. Set GIT_TELEMETRY_AUTH_TOKEN to require Authorization: Bearer <token> on every HTTP/SSE request. When the variable is unset, the server remains usable for local development but accepts requests only from loopback clients and localhost origins. Requests must use Content-Type: application/json, are size-bounded, and reject non-local origins by default. Configure GIT_TELEMETRY_ALLOWED_ROOTS (path-separated) to restrict repository arguments to approved roots.

Protocol scope

The server implements initialize, notifications/initialized, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get over its HTTP JSON-RPC and SSE transports. Unsupported MCP methods return JSON-RPC -32601 (Method not found); this implementation does not claim support for completion, sampling, logging, subscriptions, or other methods not listed above. HTTP requests are stateless; SSE uses a bounded, in-memory queue and is not a durable session store.

Shell-history boundaries

dev_activity does not read arbitrary paths. An explicit shell_history_path must be a regular file beneath a directory listed in GIT_TELEMETRY_ALLOWED_HISTORY_ROOTS (path-separated), or a detected history file under the server process user's home directory. History reads are capped at one MiB by default; set GIT_TELEMETRY_MAX_HISTORY_BYTES to a smaller local limit. Rejected paths produce a safe partial telemetry result without echoing the rejected path. The returned history_file value is passed through path scrubbing.

When GIT_TELEMETRY_AUTH_TOKEN is unset, the endpoint is intended for local development only. Configure authentication and repository/history roots before placing it behind a network-facing proxy.

Key Features & Architecture

• 16 MCP Tools: Context packs, reflog timelines, dirty diff summaries, shell correlation, dry-run merge checks, stale branch detection, and smart commit generation.
• Privacy boundary: The serializer scrubs known secret patterns and configured path patterns before telemetry or prompt return. It is defense in depth, not a guarantee that arbitrary command text or repository data is safe to disclose.
• Telemetry envelope: Successful tool results use a telemetry_payload envelope (timezone_offset, repo_checksum, confidence_score, data); tool arguments are validated against advertised inputSchema before execution.
• Safe destructive operations: safe_git_reset and safe_git_checkout require the documented two-round-trip input_required confirmation flow.

For complete documentation, tool reference, argument schemas, sample outputs, and protocol details, see HANDBOOK.md.