← 返回目录

Headroom

社区

面向 AI Agent 的本地上下文压缩层

GitHub 源仓库 ↗

★ 61.7k Stars 分类 · 开发工具非常热门

60FMRS · C

可靠性

9/20

安全与权限

11/20

维护活跃度

12/20

文档质量

15/20

安装易用性

13/20

来源显示 Headroom 是 Apache-2.0 开源项目提供的本地 MCP 服务器，版本 0.32.0，包含 headroom_compress、headroom_retrieve 和 headroom_stats。证据支持 stdio 部署及 uvx 安装；未提供特定 MCP 客户端完整兼容性清单或认证信息。

查看 FMRS 评分方法 →

Headroom MCP 服务器为 MCP 兼容主机提供压缩、检索和统计功能。它可在内容到达 LLM 前处理工具输出、日志、文件和 RAG 片段，并支持可逆压缩与本地原文检索。

工具能力

headroom_compress

压缩输入内容以减少发送给 LLM 的 token 数量。

headroom_retrieve

按需检索可逆压缩缓存中的原始内容。

headroom_stats

查看 Headroom 的压缩和节省统计。

安装接入

使用支持 uvx 的 MCP 客户端，将命令设置为 uvx，并将参数设置为 --from headroom-ai[mcp] headroom mcp serve。也可先安装 headroom-ai[mcp]，再运行 headroom mcp serve。需要 Python 3.10+；MCP 传输为 stdio。

claude_desktop_config.json

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

生成并校验客户端配置

选型与风险

适合谁

经常使用 AI 编码 Agent 的开发者
希望本地处理数据并减少 LLM 上下文开销的用户
使用多个 Agent 或 MCP 工具的工作流

不适合谁

无法运行本地进程的沙箱环境
只依赖单一供应商原生上下文压缩且不需要跨 Agent 功能的用户

所需权限

需要 MCP 主机启动本地 Headroom 进程
需要处理传入的工具输出、日志、文件、RAG 片段或会话上下文
可在本地缓存可逆压缩所需的原始内容

风险与副作用

压缩会改变发送给 LLM 的内容形式；项目声称在保持答案的同时减少 token，但实际效果取决于输入
本地缓存可能包含工具输出、文件或日志中的敏感信息
部分功能可能需要从 cdn.pyke.io 或 huggingface.co 获取运行时或模型资产
Python、平台架构或 AVX2 条件不满足时，部分功能可能回退或安装失败

常见排障

确认已安装 Python 3.10+ 及 headroom-ai[mcp]
确认客户端能找到 uvx，必要时使用绝对路径
检查 MCP 配置中的包参数是否为 --from headroom-ai[mcp] headroom mcp serve
若安装出现 TLS 或企业证书错误，检查企业 CA、REQUESTS_CA_BUNDLE、SSL_CERT_FILE 或 SSL 检查环境
若 x86 主机缺少 AVX2，检查是否触发了非 ONNX 回退路径

使用场景

压缩 MCP 工具输出、日志、文件和 RAG 结果

在编码 Agent 工作流中减少上下文 token

需要按需恢复原文的可逆压缩场景

查看压缩效果和 token 节省统计

支持客户端

暂未确认支持的客户端。