ctxpack

ctxpack-mcp

MCP server for ctxpack, token-aware context extraction for AI agents.

Agents burn context on navigation, scripts, cookie banners, and footers. ctxpack strips that and returns compact Markdown with a measured token saving. This server puts it in front of any MCP client, so an agent can pack a page before reading it instead of pulling raw HTML into its window.

MCP client (Claude Code, Codex, Gemini CLI, Cursor, …)
  → ctxpack-mcp        (this server)
    → ctxpack          (the CLI, installed separately)

It is a thin wrapper. ctxpack owns the extraction; this server owns process execution, input mapping, and turning ctxpack's exit codes into errors an agent can act on.

Requirements

• ctxpack 0.4.0 or newer. Install it separately (see below). 0.4.0 is the release that started reporting JavaScript-rendered pages instead of returning empty content, and this server depends on that.
• Nothing else at runtime. The server is a single static binary.

Install

Homebrew

brew install --cask nandemo-ya/tap/ctxpack-mcp

The cask declares depends_on formula: "atani/tap/ctxpack", so this installs both binaries.

Go

go install github.com/nandemo-ya/ctxpack-mcp/cmd/ctxpack-mcp@latest
brew install atani/tap/ctxpack   # or see the ctxpack README for other options

Prebuilt binaries

Download an archive for your platform from Releases and put ctxpack-mcp on your PATH. macOS, Linux (both arm64 and x86_64), and Windows x64 are published.

Configure your MCP client

Every client runs the same binary over stdio; only the config file differs.

Claude Code

claude mcp add ctxpack -- ctxpack-mcp          # this project only
claude mcp add -s user ctxpack -- ctxpack-mcp  # every project

Or install the plugin, which carries the same configuration:

/plugin marketplace add nandemo-ya/ctxpack-mcp
/plugin install ctxpack@nandemo-ya
/reload-plugins

The plugin ships configuration only — install the binaries first, as above. /reload-plugins registers the server without restarting the session. Confirm with claude mcp list; the entry appears as plugin:ctxpack:ctxpack.

Pick one of the two, not both: a plugin install plus a manual claude mcp add ctxpack registers the same server twice, and the agent sees two copies of every tool. Note also that the plugin exposes tools as mcp__plugin_ctxpack_ctxpack__pack rather than mcp__ctxpack__pack, which matters if you write permission rules against tool names.

Or add it to .mcp.json in your project to share it with the repository:

{
  "mcpServers": {
    "ctxpack": {
      "command": "ctxpack-mcp"
    }
  }
}

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.ctxpack]
command = "ctxpack-mcp"

Gemini CLI

In ~/.gemini/settings.json:

{
  "mcpServers": {
    "ctxpack": {
      "command": "ctxpack-mcp"
    }
  }
}

Cursor

In ~/.cursor/mcp.json, or .cursor/mcp.json for one project:

{
  "mcpServers": {
    "ctxpack": {
      "command": "ctxpack-mcp"
    }
  }
}

Tools

Tool	What it does
pack	Extract compact context from a URL or a local HTML/Markdown file
pack_content	Clean HTML or Markdown you already hold, without fetching
stats	Report cumulative token savings across recorded runs
reset_stats	Erase the savings history

pack and pack_content both accept query (moves sections relevant to your task toward the top, dropping nothing) and no_record (skip the savings history for this run).

Results are ctxpack's JSON, passed through untouched:

{
  "ok": true,
  "source": { "url": "https://example.com/docs", "fetched_at": "..." },
  "title": "Example Docs",
  "content": { "format": "markdown", "text": "..." },
  "stats": {
    "raw_html_tokens": 42100,
    "final_tokens": 7800,
    "saved_tokens": 34300,
    "reduction_percent": 81.5
  }
}

Errors

Failures come back as tool errors carrying a code, so an agent can branch on them: