使用说明

MCP Context Manager (MCM)

Experimental MCP discovery, inspection, and offline context organization for Claude Code

🎯 The Problem

Model Context Protocol (MCP) servers extend Claude Code with powerful tools, but as the MCP ecosystem grows, users lose visibility and control.

Once you enable multiple MCPs, it becomes difficult to answer basic questions:

What tools do I actually have?
Which MCPs are worth keeping enabled?
How complex is this MCP before I turn it on?
Why does my workflow feel cluttered or opaque?

MCP tool schemas can be large, verbose, and hard to reason about, and today they are mostly all-or-nothing from the user’s perspective.

🧠 What MCM Is

MCP Context Manager (MCM) is an experimental utility for Claude Code that helps you:

Discover MCP servers from names, packages, or URLs
Inspect and summarize MCP tools outside your active conversation
Organize MCP metadata locally for comparison and reference
Interact with MCP information via /mcm slash commands

MCM shifts MCP understanding out of the prompt and into a local workspace, so you can reason about tools intentionally instead of blindly enabling them.

🚫 What MCM Is Not

To be explicit:

❌ It does not dynamically load or unload MCP tools
❌ It does not change Claude’s internal MCP token usage
❌ It does not intercept, rewrite, or proxy MCP servers
❌ It does not enforce on-demand tool injection

Those capabilities would require host-level support in Claude Code, not local scripts.

MCM is an inspection and organization layer, not a runtime optimizer.

✨ What MCM Does

One-time setup

Installs a /mcm slash command into Claude Code
Creates a local workspace at ~/.mcm
Enables Claude Code to run MCP analysis scripts locally

Ongoing use

MCPs are discovered and indexed, not loaded as tools
Tool schemas are summarized and stored locally
status and validate list what was saved, so you can review servers side by side
Large MCP definitions don’t need to live in your prompt history

Think of MCM as an MCP audit and exploration toolkit.

🧪 Why This Is Useful

As MCP servers grow in number and complexity, blindly enabling them becomes risky.

MCM helps you:

Decide which MCPs are worth enabling
Understand what tools exist before using them
Keep MCP exploration out of your main working context
Avoid trial-and-error with unfamiliar or oversized MCPs

Even without runtime control, this improves clarity, confidence, and workflow hygiene.

🚀 Quick Start

Installation

git clone https://github.com/SanDiegoAIStudio/mcp-context-manager.git
cd mcp-context-manager
./install.sh

The installer copies the /mcm slash command to ~/.claude/commands/mcm.md, the scripts to ~/.claude/scripts/mcm/, and creates the workspace at ~/.mcm/.

Discover MCPs

In Claude Code, type:

/mcm discover

Paste npm package names or GitHub repository URLs, one per line. MCM looks each one up and stores the details locally.

Use the full package name, for example @modelcontextprotocol/server-filesystem. A plain name is looked up on npm exactly as written.

From a terminal:

bash ~/.claude/scripts/mcm/main.sh discover @modelcontextprotocol/server-filesystem

Results land in ~/.mcm/registry/index.json. bash ~/.claude/scripts/mcm/main.sh status lists them.

Run bash ~/.claude/scripts/mcm/main.sh discover with no names in a terminal and it asks how you want to give it the list: paste it, point to a file, or scan your Claude config. The scan reads two files:

.mcp.json in the folder you run it from
~/.claude.json, both its own mcpServers and the mcpServers of each project listed in it

It takes the package name from each server started with npx or bunx, shows you the names, and asks before it looks anything up. A server started another way is printed as skipped. When neither file names a server it can use, it prints No MCP servers found in ./.mcp.json or ~/.claude.json and exits with code 1.

Inspect a server's tools

mcm inspect <package> starts the server with npx -y in a temporary folder, asks it for its tools, and stops it after 30 seconds at most.
The stop reaches the server and the processes it started, unless one of them starts its own session; such a process can keep running after inspect returns.
It prints "This runs 's own code on your machine, the same as installing it." and asks before starting, unless you pass --yes.
It passes only PATH, HOME, USER, LANG and TMPDIR from your environment, plus certificate settings (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR), NO_PROXY, and proxy addresses (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) that carry no user name or password. The server can still read files under HOME, as any installed package can.
It saves tool names, descriptions cut to 200 characters and schema sizes.
Status and validate show real counts only for inspected servers and "not inspected" for the rest.
The token figure is the tool definitions' characters divided by 4.
A line of server output that is not JSON-RPC is ignored and counted, and inspect tells you how many there were.
If a first run times out while npx is still downloading the package, run it again.

bash ~/.claude/scripts/mcm/main.sh inspect @modelcontextprotocol/server-filesystem -- /tmp

Uninstall

./install.sh creates these and changes nothing else on your machine:

~/.claude/commands/mcm.md, the /mcm slash command
~/.claude/scripts/mcm/, holding main.sh, discover.sh, status.sh, validate.sh and mcm_engine.py
~/.mcm/, the workspace: the folders config, registry, converted/skills, embeddings, analytics, cache, backups and logs, the file config/mcm-config.json and the example list cache/mcp-list-example.txt

To remove MCM:

rm ~/.claude/commands/mcm.md
rm -r ~/.claude/scripts/mcm
rm -r ~/.mcm

The last line also deletes what discover and inspect saved under ~/.mcm/registry/; leave it out to keep that. If you installed with MCM_HOME set, the workspace is that folder instead of ~/.mcm. ~/.claude/commands and ~/.claude/scripts are shared with other tools, so the steps above leave them in place.

📊 How It Works (High Level)

/mcm commands invoke local shell scripts
Scripts call a Python analysis engine
MCP metadata is fetched from npm and GitHub
Package and repository details are written to ~/.mcm/
Claude references structured summaries instead of raw schemas

This moves MCP reasoning from prompt-time → offline-time.

What MCM sends

discover sends each npm package name you give it to registry.npmjs.org and nowhere else.
For a GitHub repository URL, discover sends the owner/repo to api.github.com (with GITHUB_TOKEN if you set it) and reads the repository's package.json from raw.githubusercontent.com.
inspect sends nothing to MCM's lookups, and npx downloads the package from the npm registry.
MCM uses no search service. The only key it reads is GITHUB_TOKEN, and only for api.github.com.
Set GITHUB_TOKEN in your shell to raise GitHub's rate limit; MCM reads it from the environment and stores it nowhere.
Nothing else leaves your machine: no file contents, no paths and no config. Each request is printed as it happens.
A name must look like an npm package, a GitHub repository URL or a plain name; anything else is skipped and nothing is sent for it.
A redirect to another host is refused, so a token or key never follows one.

Known limits

discover saves package and repository details only. Real tool counts come from mcm inspect, which runs the server.

⚠️ Project Status

Early-stage / experimental

Command routing may require refinement
Heuristics are evolving
Output formats may change
Not production-hardened

This project is intended as a developer utility and research sandbox.

🧭 Future Direction (Not Implemented)

These are ideas, not current features:

Semantic search across MCP tools
Usage-based MCP recommendations
Improved schema parsing (AST-based)
Host-integrated tool loading (if supported in the future)

Tests

python3 -m unittest discover -s tests -v

The story (then and now)

Then. On Saturday, November 15, 2025, I asked Claude Code: "which are the best MCP's for me?" I had Playwright hooked up and didn't know what else to add. A couple of hours later I pasted in Anthropic's new post, "Code execution with MCP" (published November 4), with one line of my own: "trying to learn the best way to solve this prob." The problem: every server you add loads all of its tool definitions into the context window before you type a word. I was on Claude Code 2.0.41 with Sonnet 4.5, and I had no tool I trusted to show me what a server would cost before I turned it on.

The first commit landed at 12:04. At 14:13 I typed /mcm discover, and at 14:18 I wrote "lets do a git save and push to github, the MCM app since it is working." It was the busiest day in my November 8 to December 11 logs: 20 sessions, 1,924 tool calls.

It also promised too much. The setup guide said MCM would "save 90-95%" of context. Nothing measured that. The cost estimate was a fixed number.

Now. Claude Code shows per-server context cost on its own these days, and other tools scan servers. One thing is still missing: a local look before you install, with nothing sent anywhere. So the re-release does one honest job. mcm inspect starts a server in a throwaway folder, asks for its real tools and counts the tokens. The filesystem server came back with 14 tools, about 3,274 tokens, in 3.6 seconds. 114 tests pass, and the README now says what it doesn't do.

State: experimental. I don't run it daily. Next up: pin a server's tools and flag when they change.

📄 License

MIT License. See LICENSE for details.