mcp-trim

MCP tools often return huge JSON responses — full of fields the agent never uses. mcp-trim automatically strips those away, so Claude only sees the fields that matter. Less noise, fewer tokens, faster sessions.

TL;DR: Install → define which fields to keep → every matching MCP response gets trimmed automatically. Or let auto-learning figure it out for you.

---

Table of Contents

• How It Works
• Use Cases
• Quick Start
• Creating Rules
• Examples
• Auto-Learning
• Token Savings
• Configuration Reference
• CLI Reference
• Library API
• Uninstall

---

How It Works

      Claude calls MCP tool
               │
               ▼
    Tool returns full response
               │
               ▼
         mcp-trim hook
               │
               ▼
        Trimmed response
               │
               ▼
   Claude sees only needed fields

The plugin hooks into Claude Code's PostToolUse event. When an MCP tool (any tool named mcp__*) returns a response, mcp-trim checks your rules, keeps only the fields you specified, and passes the trimmed result back to Claude.

Built-in tools (Bash, Read, Edit, etc.) are never affected.

---

Use Cases

Automated CI/CD pipelines

If your agent runs repeated workflows — triaging issues, reviewing PRs, checking build status — every MCP call returns the same bloated response. Trimming rules let you define once which fields matter and save tokens on every subsequent call.

Long-running coding sessions

During extended sessions Claude may call the same MCP tools dozens of times. Without trimming, each call burns tokens on fields like permissions, URLs, and metadata the agent never reads. Over a session, that can add up to tens of thousands of wasted tokens.

Multi-tool orchestration

When the agent coordinates across multiple MCP servers (GitHub + Jira + Slack, for example), responses compound quickly. Trimming each server's output to just the fields used keeps the context window lean and lets the agent handle longer conversations before hitting limits.

Predictable API shapes

MCP tools that wrap REST APIs (GitHub, Jira, Linear, Notion, etc.) return stable JSON shapes. Once you know which fields the agent actually uses, a trimming rule is a one-time setup that pays off on every call — no code changes, no prompt engineering.

Auto-learning for new tools

When you start using a new MCP server and don't yet know which fields matter, enable auto-learning and let mcp-trim observe a few sessions. After enough feedback, it suggests rules automatically — no manual field analysis required.

---

Quick Start

Option A: Claude Code Plugin (Recommended)

/plugin marketplace add pask00/mcp-trim
/plugin install mcp-trim@mcp-trim

Hooks and the field-usage-feedback skill are set up automatically. Just create your first rule:

mcp-trim init
mcp-trim set github-repos \
  --tool "mcp__github__get_repository" \
  --keep "id,name,full_name,html_url,description"

Option B: npm (Manual Setup)

# 1. Install
npm install -g mcp-trim

# 2. Register the hooks with Claude Code
mcp-trim install            # local project
mcp-trim install --global   # all projects

# 3. Create your first rule
mcp-trim init
mcp-trim set github-repos \
  --tool "mcp__github__get_repository" \
  --keep "id,name,full_name,html_url,description"

That's it — every matching MCP response is now trimmed automatically.

---

Creating Rules

Simple: comma-separated fields

mcp-trim set github-repos \
  --tool "mcp__github__get_repository" \
  --keep "id,name,full_name,html_url,description"

Nested: JSON shape

Use --keep-json when you need to filter nested objects:

mcp-trim set github-repos \
  --tool "mcp__github__get_repository" \
  --keep-json '{"id":true,"name":true,"owner":{"login":true}}'

Regex: match multiple tools

The --tool pattern supports regex, so you can match a whole MCP server:

mcp-trim set github-all \
  --tool "mcp__github__.*" \
  --keep "id,name,title,state"

Agent self-configuration

Claude Code can create rules on the fly via Bash — useful when the agent encounters a verbose response and wants to trim it for future calls:

mcp-trim set jira-issues --tool "mcp__jira__list_issues" --keep "key,summary,status,assignee"

---

Examples

The examples/ folder contains ready-to-use configs for common MCP servers. Each example has its own directory with a config.json and a README.md explaining the scenario.