How do I install MCP Optimizer?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does MCP Optimizer need an API key?

No required environment variable is listed on this record.

What transport does MCP Optimizer use?

MCP Optimizer runs locally over stdio.

When was MCP Optimizer last checked?

Last checked 2026-10-28. Comprehensive MCP optimization toolkit for Claude Code — diagnose, health-check, optimize, and convert MCP servers.

MCP Optimizer MCP server

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: MIT
Last checked: 2026-10-28

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

mcp-optimizer

Marketplace-ready Claude Code plugin for MCP diagnostics, usage analysis, project scoping, and on-demand skill conversion.

mcp-optimizer helps you answer four separate questions:

Are my MCP servers healthy?
Which servers are actually wasting tokens?
Should I keep MCP but scope it to this project?
Should I convert a heavy MCP server into local on-demand skills?

It ships both:

explicit plugin commands in commands/
matching bundled Skills in skills/

Each /mcp-optimizer:* command is a thin entrypoint that delegates to the corresponding bundled Skill, so the workflow logic stays in one place.

Why This Exists

When an MCP server is connected to Claude Code, its tool schemas are loaded into every conversation whether you use them or not.

Scenario	Token cost
Linear MCP (31 tools)	~3,000+ tokens/conversation
GitHub MCP (20+ tools)	~2,000+ tokens/conversation
3 MCP servers connected	~6,500+ tokens/conversation
Local skill used only when needed	~0 idle tokens

That creates three common problems:

Large MCP schemas waste tokens even when idle.
Broken or duplicate servers pollute context and slow down sessions.
Global MCP configs are often broader than a single project needs.

Installation

From GitHub (Recommended)

Add this repository as a marketplace.

/plugin marketplace add choam2426/mcp-optimizer

Install the plugin.
```
/plugin install mcp-optimizer
```
Restart Claude Code if prompted, then verify installation.
```
/help
```

From Another Marketplace

If mcp-optimizer is included in an existing marketplace:

/plugin marketplace add your-org/claude-plugins
/plugin install mcp-optimizer@your-org

Components At a Glance

Command	Category	Use it for	Main inputs	Writes files?
`/mcp-optimizer:mcp-doctor`	Diagnostics	Check server health, duplicates, and credentials	`--server`, `--fix`	No
`/mcp-optimizer:mcp-audit`	Analysis	Measure token waste from real session usage	`--scope`	No
`/mcp-optimizer:mcp-optimize`	Optimization	Create a smaller project-local `.mcp.json`	`--dry-run`, `--min-sessions`	Yes, after confirmation
`/mcp-optimizer:mcp-to-skills`	Conversion	Convert an MCP server into local on-demand skills	`<server-command>`	Yes, creates `.claude/skills/...`

Recommended Workflow

Start with diagnostics:
```
/mcp-optimizer:mcp-doctor
```
Once servers are healthy, measure actual waste:
```
/mcp-optimizer:mcp-audit
```
Choose the execution path that fits your goal:
- Keep MCP, but only for this project:
```
/mcp-optimizer:mcp-optimize
```
- Convert a heavy server into on-demand local skills:
```
/mcp-optimizer:mcp-to-skills npx @linear/mcp-server
```

The important distinction is:

mcp-doctor is a diagnostic command, not an optimization command.
mcp-audit is an analysis command that tells you where waste comes from.
mcp-optimize and mcp-to-skills are the actual optimization paths.

Command Reference

Diagnostics: `/mcp-optimizer:mcp-doctor`

Use mcp-doctor when you want to inspect MCP server health before changing anything.

What it does:

tests configured MCP servers
measures response time
finds duplicate tool names across servers
flags missing or suspicious credentials
suggests concrete remediation steps

Command form:

/mcp-optimizer:mcp-doctor [--server <name>] [--fix]

Arguments:

Argument	Meaning	Default
`--server <name>`	Check only one configured MCP server	Check all configured servers
`--fix`	Include concrete remediation commands in the report	Off

Default behavior:

Runs as a read-only health check.
Does not modify your config.
If --fix is present, it suggests commands or follow-up actions, but still does not edit anything automatically.

What to expect:

health report by server
response times
duplicate tool findings
missing credential warnings
recommended next step, usually /mcp-optimizer:mcp-audit after issues are resolved

Examples:

/mcp-optimizer:mcp-doctor
/mcp-optimizer:mcp-doctor --server github
/mcp-optimizer:mcp-doctor --fix

Analysis: `/mcp-optimizer:mcp-audit`

Use mcp-audit when you want evidence about token waste before deciding what to keep, remove, scope, or convert.

What it does:

reads Claude Code session history
estimates per-server schema overhead
shows which tools were used vs never used
ranks optimization opportunities
suggests conversion commands for high-waste servers

Command form:

/mcp-optimizer:mcp-audit [--scope project|all]

Arguments:

Argument	Meaning	Default
`--scope project`	Analyze sessions for the current project only	Yes
`--scope all`	Analyze sessions across all projects Claude can inspect	No

Default behavior:

If no scope is provided, project scope is used.
The command only analyzes available session history. It does not modify config or generated skills.

What to expect:

ranked token waste by MCP server
total estimated waste
unused tool ratios
recommendations for /mcp-optimizer:mcp-optimize and /mcp-optimizer:mcp-to-skills

Examples:

/mcp-optimizer:mcp-audit
/mcp-optimizer:mcp-audit --scope project
/mcp-optimizer:mcp-audit --scope all

Optimization: `/mcp-optimizer:mcp-optimize`

Use mcp-optimize when you still want MCP, but not every global server should load in this project.

What it does:

analyzes which servers look relevant to the current project
proposes a reduced project-local .mcp.json
estimates token savings
writes the file only after confirmation

Command form:

/mcp-optimizer:mcp-optimize [--dry-run] [--min-sessions <N>]

Arguments:

Argument	Meaning	Default
`--dry-run`	Show the optimization plan without writing `.mcp.json`	Safe planning behavior
`--min-sessions <N>`	Require at least `N` sessions before making stronger recommendations	`5`

Default behavior:

Treats optimization as a plan-first workflow.
Shows the proposed .mcp.json before writing.
Writes only the project-local .mcp.json.
Never modifies global Claude config such as ~/.claude.json.

What to expect:

keep/remove recommendation per MCP server
estimated savings per session
full proposed .mcp.json
confirmation step before writing

Examples:

/mcp-optimizer:mcp-optimize
/mcp-optimizer:mcp-optimize --dry-run
/mcp-optimizer:mcp-optimize --min-sessions 10

Conversion: `/mcp-optimizer:mcp-to-skills`

Use mcp-to-skills when a server has many tools but you only need a few of them on demand.

What it does:

inspects the target MCP server
reads tool schemas
generates one local Claude Code skill per tool
defaults to proxy mode unless native mode is clearly better

Command form:

/mcp-optimizer:mcp-to-skills <server-command>

Arguments:

Argument	Meaning	Required
`<server-command>`	MCP server command to inspect and convert, such as `npx @linear/mcp-server`	Yes

Default behavior:

Requires a concrete MCP server command.
Writes generated local skills under .claude/skills/.
Prefers proxy mode by default.

What to expect:

detected service name
generated skill directories
per-tool descriptions
example natural-language requests for the generated skills

Examples:

/mcp-optimizer:mcp-to-skills npx @linear/mcp-server
/mcp-optimizer:mcp-to-skills uvx mcp-server-gitlab

Command Vs Skill

This plugin exposes the same workflows in two forms:

commands/: explicit user-invoked commands such as /mcp-optimizer:mcp-audit
skills/: bundled Skills Claude can discover automatically from natural-language requests

In this repository:

the command is the public explicit entrypoint
the matching Skill is the canonical workflow implementation
the command delegates to the matching Skill instead of duplicating instructions

That means you can either:

invoke the command directly, or
ask in natural language and let Claude discover the bundled Skill

Generated Local Skills

/mcp-optimizer:mcp-to-skills creates local skills under .claude/skills/.

Important points:

Generated local skills are not namespaced as /mcp-optimizer:*.
They are separate local skills for your project or working tree.
Claude should discover them when the user asks for that workflow in natural language.

Example request after conversion:

List open Linear issues for the Engineering team

Example Scenarios

Situation	Start with	Why
"I think one of my MCP servers is broken"	`/mcp-optimizer:mcp-doctor`	Diagnose health before optimizing
"I want to know where token waste is coming from"	`/mcp-optimizer:mcp-audit`	Measure actual usage and waste
"This project should not load every global MCP server"	`/mcp-optimizer:mcp-optimize`	Keep MCP but scope it locally
"This server is too heavy, but I still need a few tools"	`/mcp-optimizer:mcp-to-skills`	Convert tools into local on-demand skills

Requirements And Notes

Python 3.10+
Claude Code installed and running
MCP server environment variables must already be available when using mcp-doctor or mcp-to-skills
mcp-audit depends on available Claude Code session history
mcp-optimize only writes a project-local .mcp.json

License

MIT

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install MCP Optimizer?

Does MCP Optimizer need an API key?

What transport does MCP Optimizer use?

When was MCP Optimizer last checked?

Documentation

mcp-optimizer

Why This Exists

Installation

From GitHub (Recommended)

From Another Marketplace

Components At a Glance

Recommended Workflow

Command Reference

Diagnostics: /mcp-optimizer:mcp-doctor

Analysis: /mcp-optimizer:mcp-audit

Optimization: /mcp-optimizer:mcp-optimize

Conversion: /mcp-optimizer:mcp-to-skills

Command Vs Skill

Generated Local Skills

Example Scenarios

Requirements And Notes

License

Diagnostics: `/mcp-optimizer:mcp-doctor`

Analysis: `/mcp-optimizer:mcp-audit`

Optimization: `/mcp-optimizer:mcp-optimize`

Conversion: `/mcp-optimizer:mcp-to-skills`