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_payloadenvelope (timezone_offset,repo_checksum,confidence_score,data); tool arguments are validated against advertisedinputSchemabefore execution. - Safe destructive operations:
safe_git_resetandsafe_git_checkoutrequire the documented two-round-tripinput_requiredconfirmation flow.
For complete documentation, tool reference, argument schemas, sample outputs, and protocol details, see HANDBOOK.md.
Metadata
Release files for git-telemetry-mcp 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| git_telemetry_mcp-0.1.3.tar.gz | 126.8 kB | Without provenance | Details for git_telemetry_mcp-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| git_telemetry_mcp-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for git_telemetry_mcp-0.1.3-py3-none-any.whl |
Total release size: 187.4 kB
Release files / git_telemetry_mcp-0.1.3.tar.gz
| Download URL | git_telemetry_mcp-0.1.3.tar.gz |
|---|---|
| Size | 126.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd3d2680461e8f70029a58268297cdd16a9bf8074caf1b73098ca3baef61a344
|
|
BLAKE2b-256 checksum How to use checksums |
728c82e149e79c7a401b0629f7328a8151aaa168704f82e8d59c90787020333f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / git_telemetry_mcp-0.1.3-py3-none-any.whl
| Download URL | git_telemetry_mcp-0.1.3-py3-none-any.whl |
|---|---|
| Size | 60.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
657d53ff302377d9d906e0ec2bc45cad6dedb449c67ef854ecc0b5e47bffd082
|
|
BLAKE2b-256 checksum How to use checksums |
5ed7120986dd3fea43abd6adbbd7f638832d74ede7c7692832bff3354cf948ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for git-telemetry-mcp 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.