M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
H

Headroom

Community
A local context-compression layer for AI agents
How to install ↓ Compare GitHub source repository ↗
Category
Dev Tools #121 of 438
Stars
★ 75.9k Very popular
Transport
stdio (local process)
Runtime
Python 3.10+
Credentials
No credential needed
License
Apache-2.0
Last commit
Tools
3
60FMRS · C

The source identifies Headroom as an Apache-2.0 open-source local MCP server, version 0.32.0, exposing headroom_compress, headroom_retrieve, and headroom_stats. The evidence supports stdio deployment and uvx installation; it does not provide a complete MCP-client compatibility list or authentication details.

Strongest · Documentation 15/20 Weakest · Reliability 9/20

Reliability
9/20
Security and permissions
11/20
Maintenance
12/20
Documentation
15/20
Setup experience
13/20
Why each score
Reliability 9/20
The manifest gives a concrete PyPI, uvx, stdio launch contract, and the README names three MCP tools. However, no server source, committed tests, or CI workflow contents are supplied to verify initialization, tool listing, parameters, or error paths. Model downloads, ONNX runtime requirements, and optional backends add further failure modes, so the score remains modest.
Security and permissions 11/20
The README claims local execution and local data handling, and no malware, credential theft, or default remote-command red line is evident. However, the design includes proxy forwarding, external TLS downloads, shared memory, local CCR caching, and writes to CLAUDE/AGENTS files. Permission boundaries, sensitive-data retention, access control, and confirmation for consequential actions are not sufficiently documented, so points are deducted.
Maintenance 12/20
The project states Apache-2.0, provides an identifiable repository, website, and PyPI version 0.32.0, and is not archived. The material also gives signals of substantial attention and an ongoing release line. Still, recent commits, actual CI, dependency-update practice, vulnerability response, and maintainer accountability cannot be verified from the supplied material, preventing a near-perfect score.
Documentation 15/20
The README covers installation, MCP configuration, proxy use, platform constraints, optional dependencies, TLS troubleshooting, limitations, and some performance evidence in considerable breadth. Points are deducted because reviewable MCP tool schemas, return structures, authentication and authorization, resource handling, and privacy policy are absent; repository identity and some links also mix headroomlabs-ai with chopratejas.
Setup experience 13/20
The manifest specifies the PyPI package, uvx runtime, stdio transport, pinned version, and command arguments, while the README includes an absolute-path Codex configuration example. The path is nevertheless complicated by Python/uv requirements, optional extras, model and ONNX downloads, platform differences, Intel macOS workarounds, and corporate TLS cases. No file-level execution evidence demonstrates an end-to-end working connection.

Static review · not runListed 2026-07-29

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesUses the network

Best for

  • Developers who use AI coding agents regularly
  • Users who want local processing and lower LLM context costs
  • Workflows combining multiple agents or MCP tools

Not for

  • Sandboxed environments that cannot run local processes
  • Users satisfied with a single provider's native compaction and without a need for cross-agent features

Required permissions

  • The MCP host must start a local Headroom process
  • The server must process incoming tool outputs, logs, files, RAG chunks, or conversation context
  • Reversible compression may cache original content locally

Risks and side effects

  • Compression changes the form of content sent to the LLM; the project claims answer preservation, but results depend on the input
  • The local cache may contain sensitive information from tool outputs, files, or logs
  • Some features may download runtime or model assets from cdn.pyke.io or huggingface.co
  • Unsupported Python, platform, or AVX2 conditions can cause installation failures or feature fallbacks

Setup

Before you start

Runtime：Python 3.10+

Other optional settings (14)
HEADROOM_OUTPUT_SHAPER optional Set to 1 to enable output token reduction (verbosity steering and effort routing); off by default.
HEADROOM_OUTPUT_HOLDOUT optional Fraction (0-1) of conversations left unshaped as a control group for measured output savings.
HEADROOM_EMBEDDER_RUNTIME optional Set to pytorch_mps to offload the memory embedder to Apple GPU.
HEADROOM_UPDATE_CHECK optional Set to off to disable the daily background PyPI update check at startup.
HEADROOM_TLS_STRICT optional Set to 0 in SSL-inspection environments to relax Python 3.13 strict TLS verification (only clears VERIFY_X509_STRICT).
ORT_STRATEGY optional Set to system to use a system-installed ONNX Runtime instead of downloading one.
ORT_LIB_LOCATION optional Path to a system ONNX Runtime lib/ directory, used with ORT_STRATEGY=system.
ORT_DYLIB_PATH optional Absolute path to libonnxruntime.dylib dlopen'd at runtime.
ORT_PREFER_DYNAMIC_LINK optional Set to 1 to force dynamic linking of ONNX Runtime.
HF_HUB_OFFLINE optional Set to 1 to use a pre-downloaded kompress model instead of contacting HuggingFace.
HF_ENDPOINT optional Set to a trusted HuggingFace mirror for model downloads.
REQUESTS_CA_BUNDLE optional Path to a CA bundle with your corporate CA, used by requests/huggingface_hub downloads.
SSL_CERT_FILE optional Path to a CA certificate file for corporate SSL-inspection environments.
CURL_CA_BUNDLE optional Path to a CA bundle for corporate SSL-inspection environments.

In an MCP client that supports uvx, set the command to uvx and the arguments to --from headroom-ai[mcp] headroom mcp serve. You may also install headroom-ai[mcp] first and then run headroom mcp serve. Python 3.10+ is required; the MCP transport is stdio.

MCP config · JSON 
{"command":"uvx","args":["--from","headroom-ai[mcp]","headroom","mcp","serve"]}

Works in clients that read an "mcpServers" key. For clients such as VS Code that use a different key, the configurator below converts it.

.vscode/mcp.json
{
  "command": "uvx",
  "args": [
    "--from",
    "headroom-ai[mcp]",
    "headroom",
    "mcp",
    "serve"
  ]
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Generate and validate client config

Check that it works

Check that headroom_compress, headroom_retrieve, and headroom_stats appear in your MCP client's tool list; calling headroom_stats and getting compression statistics back proves the connection works.

Troubleshooting

  1. Confirm that Python 3.10+ and headroom-ai[mcp] are installed
  2. Confirm that the client can locate uvx; use an absolute path if necessary
  3. Check that the MCP configuration arguments are --from headroom-ai[mcp] headroom mcp serve
  4. For TLS or corporate-certificate errors, check the corporate CA, REQUESTS_CA_BUNDLE, SSL_CERT_FILE, or SSL-inspection setup
  5. On x86 hosts without AVX2, check whether the non-ONNX fallback path is being used

Things to try

Once connected, you can ask your AI assistant things like:

  • Compress this tool's JSON output to save tokens
  • Retrieve the original uncompressed content for what you just compressed (CCR)
  • Show compression stats so I can see how many tokens have been saved

Tools 3

headroom_compress read-only
Compresses input content to reduce the number of tokens sent to an LLM.
headroom_retrieve read-only
Retrieves original content from the reversible-compression cache when needed.
headroom_stats read-only
Shows Headroom compression and token-savings statistics.

Use cases

Compress MCP tool outputs, logs, files, and RAG results
Reduce context tokens in coding-agent workflows
Use reversible compression with on-demand original retrieval
Inspect compression and token-savings statistics

Overview

The Headroom MCP server provides compression, retrieval, and statistics for MCP-compatible hosts. It processes tool outputs, logs, files, and RAG chunks before they reach an LLM, with reversible compression and local retrieval of originals.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 63.3k · Tools 2 Compare with this →
Compare with other MCP servers

Source revision fbf7bc3278c1 Data synced 2026-10-19 Read the FMRS scoring method