zhicho's Blog

工作随记 / 公开笔记

Headroom MCP 基础笔记

发布于 2026年6月8日8 个章节

Headroom MCP 基础笔记

8 个章节

Headroom 是一个本地上下文压缩层，可以作为 CLI、代理、库和 MCP server 使用。

  • #AI
  • #MCP

Headroom MCP 基础笔记

日期：2026-06-08

安装状态

  • 已安装：headroom-ai 0.23.0
  • 安装方式：pipx
  • Python 环境：pipx 下载的独立 Python 3.13.13
  • 可执行命令：headroom

验证命令：

headroom --version
headroom --help

当前验证结果：

headroom, version 0.23.0

它是什么

Headroom 是一个本地上下文压缩层，可以作为 CLI、代理、库和 MCP server 使用。

它不是 Codex skill。当前安装的是 Headroom CLI，并通过 headroom mcp install 注册为 MCP server。

MCP 配置

已执行：

headroom mcp install

安装器输出显示已注册到：

  • Claude
  • Codex

Codex 配置位置：

~/.codex/config.toml

当前 Codex MCP 配置片段：

[mcp_servers.headroom]
command = "headroom"
args = ["mcp", "serve"]

MCP server 实际由 Codex 在启动时通过 stdio 调用：

headroom mcp serve

所以一般不需要手动运行 headroom mcp serve。

提供的 MCP 工具

Headroom MCP 的工具名通常包括：

  • headroom_retrieve
  • headroom_compress
  • headroom_stats

在 MCP 客户端里，工具可能显示成：

mcp__headroom__headroom_retrieve
mcp__headroom__headroom_compress
mcp__headroom__headroom_stats

这是正常的 MCP 命名空间规则：mcp__<server>__<tool>。

Proxy 用法

MCP server 负责按需工具调用；如果要让所有请求自动经过 Headroom 压缩，还需要启动 Headroom proxy。

启动默认代理：

headroom proxy

默认地址：

http://127.0.0.1:8787

Claude Code 示例：

ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude

OpenAI 兼容客户端示例：

OPENAI_BASE_URL=http://127.0.0.1:8787/v1 your-app

Codex CLI 便捷包装：

headroom wrap codex

wrap 会启动 proxy，并用合适的环境变量启动目标工具。

常用命令

检查 MCP 状态：

headroom mcp status

安装 MCP：

headroom mcp install

移除 MCP：

headroom mcp uninstall

查看 proxy 参数：

headroom proxy --help

查看 wrapper 支持的工具：

headroom wrap --help

当前注意点

  • headroom mcp install 已把 Headroom 写入 Codex 配置，但当前 Codex 会话通常需要重启后才能加载新 MCP server。
  • headroom mcp status 当前显示 proxy 未运行，这是正常状态；只有执行 headroom proxy 或 headroom wrap ... 后才会运行。
  • 本机 Homebrew 默认 python3 是 Python 3.14.5，直接安装 headroom-ai[all] 会因 PyO3 最高支持 Python 3.13 而失败。
  • 这次已绕过该问题，使用 pipx --python 3.13 --fetch-python=missing 安装成功。

基础测试用例

  1. CLI 是否可用
headroom --version

期望：输出 headroom, version 0.23.0 或更高版本。

  1. Codex MCP 配置是否存在
sed -n '260,275p' ~/.codex/config.toml

期望：能看到 [mcp_servers.headroom]，并且 command = "headroom"、args = ["mcp", "serve"]。

  1. MCP server 启动命令是否存在
headroom mcp serve --help

期望：显示 Start the MCP server，并列出 --proxy-url、--debug 等参数。

  1. Proxy 是否可启动
headroom proxy

期望：代理监听 127.0.0.1:8787。测试结束后用 Ctrl+C 停止。

  1. 重启 Codex 后检查 MCP 工具

重启 Codex 后，在可用工具列表中确认是否出现 Headroom MCP 工具。

期望：能看到类似 mcp__headroom__headroom_retrieve 的工具名。