mcp-nap
Your MCP servers sleep until you call a tool.
Claude Code, Cursor and VS Code each start their own copies of every stdio MCP server long before anything calls one, and keep them running: Claude Code one set per session, Cursor as soon as a window opens, VS Code one set per chat. mcp-nap stands in for each server, answers the client's startup requests from a cache, and starts the real server only when one of its tools is called. After 10 quiet minutes it stops it again. The model sees the same tool list either way; the saving is the idle node processes and their memory.
uv tool install mcp-nap
mcp-nap wrap # Claude Code
mcp-nap wrap --client cursor # Cursor
mcp-nap wrap --client vscode # VS Code
wrap rewrites every stdio server in that client's config to run through mcp-nap and prints where it saved a backup first. Name servers to wrap only those: mcp-nap wrap playwright shadcn. What to do after wrap depends on the client, below. Servers that hold state lose it at the 10-minute stop: Playwright's open browser is the usual one, see Servers that keep state.
To try it without installing:
uvx mcp-nap wrap
That works, but uvx stays running as the parent of every wrapped server, so each one costs about 56 MB instead of 22 MB. With four servers that is 223 MB per session instead of 89 MB. It also writes uvx mcp-nap into the config with no version, so which release runs is up to uv's cache at each start. Install it with uv tool install (or pipx install mcp-nap) once you keep it.
Let your agent set it up
Paste this to Claude Code, Cursor, VS Code chat or any agent that can run commands on your machine:
Set up mcp-nap (https://github.com/ashuwhy/mcp-nap) so my stdio MCP servers sleep until a tool is called.
1. If `uv --version` fails, install uv the way https://docs.astral.sh/uv/getting-started/installation/ says. Run `uv tool install mcp-nap`, then `mcp-nap --help`. If mcp-nap is not found, run `uv tool update-shell` and use a new shell.
2. Check which of these I use and list the stdio servers (entries with a "command") in each. Read the files only; never print env values or headers, they often hold API keys.
- Claude Code: `claude` is on PATH; top-level "mcpServers" in ~/.claude.json
- Cursor: "mcpServers" in ~/.cursor/mcp.json
- VS Code: "servers" in ~/Library/Application Support/Code/User/mcp.json (macOS), %APPDATA%\Code\User\mcp.json (Windows) or ~/.config/Code/User/mcp.json (Linux)
3. Show me the list and ask which to wrap. Flag servers that keep state between calls (Playwright and other browser servers) and suggest --idle 0 for them.
4. Wrap with mcp-nap only, never by editing a config yourself:
Claude Code: mcp-nap wrap NAME...
Cursor: mcp-nap wrap NAME... --client cursor
VS Code: mcp-nap wrap NAME... --client vscode
Wrap the stateful ones in a separate run with --idle 0 added.
5. Tell me what each run printed (backup path, any note, the restart step), and that `mcp-nap unwrap` with the same --client undoes it.
Clients
Checked against Claude Code 2.1, Cursor 3.29 and VS Code 1.146 on macOS. All three change how they run servers often.
Claude Code
Every session starts every stdio server and keeps it until the session ends, so five open sessions hold five idle copies of each. mcp-nap wrap edits the user servers in ~/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json) through claude mcp, because live sessions write that file too. Then:
Restart open Claude Code sessions to pick this up.
Cursor
As soon as a signed-in window opens, Cursor starts every enabled server, before any chat, and keeps it until you quit. A second window or workspace can add more copies. mcp-nap wrap --client cursor edits ~/.cursor/mcp.json (%USERPROFILE%\.cursor\mcp.json on Windows). Then:
Cursor starts the new command by itself, but copies already running keep the old one: toggle each changed server off and on in Cursor Settings > Tools & MCP, or quit and reopen Cursor.
Project .cursor/mcp.json files are not touched.
VS Code
Chat in VS Code 1.146 runs on the Copilot agent host, which starts a full set of servers for every chat session and keeps it until you delete the chat or quit. Archiving a chat doesn't stop its set. Opening an empty new chat starts one more, dropped after 5 minutes if you never type. Wrapped, every one of those copies is a sleeping 22 MB wrapper, and the real server runs only around a tool call.
mcp-nap wrap --client vscode edits the default profile's mcp.json: ~/Library/Application Support/Code/User/mcp.json on macOS, %APPDATA%\Code\User\mcp.json on Windows, ~/.config/Code/User/mcp.json on Linux (or under $XDG_CONFIG_HOME). Then:
VS Code picks up the new command in each chat the next time you send a message in it, or quit and reopen VS Code.
- A server with
"sandboxEnabled": trueis left alone: the sandbox would not let mcp-nap write its cache. - On the older Local harness (
chat.defaultToCopilotHarnessoff), VS Code already starts servers on first use, so mcp-nap only adds the idle stop. That harness also needsrg(ripgrep) on PATH to start any sandboxed server, wrapped or not; without it the server exits withripgrep (rg) not found. - Other profiles, VS Code Insiders and workspace
.vscode/mcp.jsonfiles are not touched.
Cursor and VS Code config files
wrap and unwrap write the file the way it was laid out (indent, line endings, key order), so unwrap gives back the same bytes. A file laid out by hand gets reformatted once, with a note that the backup has it as it was. A file with comments or trailing commas is refused and left as it is, since those would be lost.
Any other client
mcp-nap is a plain stdio server, so any client that runs stdio servers can use it. Put it in front of the server's command:
"playwright": {
"command": "mcp-nap",
"args": ["playwright", "--", "npx", "-y", "@playwright/mcp@latest"]
}
The first argument names the cache file, so give each server its own. If the client doesn't see your shell's PATH, use the full path that command -v mcp-nap prints. (wrap already writes the full path.)
What it saves
With four servers, one session held 948 MB bare and 89 MB wrapped.
Measured on my laptop with four npx servers (mui, shadcn, playwright, chrome-devtools) per session. A session here is what Claude Code does at startup: spawn every server, initialize, list tools, then sit idle. In Cursor and VS Code, count one session per set of copies the client starts.
machine: Darwin arm64, 16 GB RAM, 6026 MB free at start, Python 3.15.2, node v22.16.0
uv 0.10.2, uv tool install picked Python 3.13.5
env: npm_config_prefer_offline=true npm_config_update_notifier=false CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1 CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1
Resident memory, 4 servers per session, wrapper cache warm:
| sessions | bare | mcp-nap (uv tool install) | mcp-nap (python3 mcp_nap.py) | mcp-nap (uvx) |
|---|---|---|---|---|
| 1 | 948 MB (948 MB/session) | 89 MB (89 MB/session) | 75 MB (75 MB/session) | 222 MB (222 MB/session) |
| 3 | 2635 MB (878 MB/session) | 268 MB (89 MB/session) | 228 MB (76 MB/session) | 668 MB (223 MB/session) |
| 5 | 3836 MB (767 MB/session) | 447 MB (89 MB/session) | 379 MB (76 MB/session) | 1115 MB (223 MB/session) |
- mcp-nap (uv tool install) wrapper: 22.4 MB per wrapped server
- mcp-nap (python3 mcp_nap.py) wrapper: 19.0 MB per wrapped server
- mcp-nap (uvx) wrapper: 55.7 MB per wrapped server, uvx stayed as parent in 20 of 20
- memory pressure at 3 sessions, bare: the compressor grew 486 MB while measuring, so that cell reads up to that much low
- memory pressure at 5 sessions, bare: the compressor grew 826 MB while measuring, so that cell reads up to that much low
Delay, median of 3 runs (nap = python3 mcp_nap.py; cold = no mcp-nap cache yet, asleep = warm cache, server not started):
| server | bare start | nap start cold | nap start warm | uv tool start warm | uvx start warm | bare call | nap call asleep |
|---|---|---|---|---|---|---|---|
| mui | 515 ms | 517 ms | 34 ms | 33 ms | 73 ms | 6 ms | 541 ms |
| shadcn | 536 ms | 531 ms | 33 ms | 28 ms | 69 ms | 8 ms | 504 ms |
| playwright | 523 ms | 532 ms | 34 ms | 29 ms | 72 ms | 927 ms | 1.1 s |
| chrome-devtools | 593 ms | 600 ms | 33 ms | 28 ms | 68 ms | 12 ms | 568 ms |
The bare cells at 3 and 5 sessions were measured while macOS was compressing pages, so they read low and the saving there is larger than shown. The 1-session row had no pressure.
The delay is paid on the first call to a server after it went to sleep, then calls run at the bare speed until it idles out. Startup gets faster, because the tool list comes from the cache instead of a fresh node process.
To rerun it on your machine (needs uv and node, about 5 minutes):
python3 bench/measure.py
It builds the wheel from the checkout, installs it with uv tool install into a temp dir, uses its own temp cache, and skips a session count when there isn't free memory for it. --sessions 1,3 and --reps 1 make it shorter; --skip-uv runs only bare and python3 mcp_nap.py.
RSS counts shared pages (the node binary, libc) once per process, so every column reads high. Read the difference between columns, not the absolute numbers.
How it works
The first time a wrapped server runs, mcp-nap starts it, passes everything through, and saves its initialize, tools/list, resource and prompt list replies under ~/.cache/mcp-nap ($XDG_CACHE_HOME if set). After that, a new session gets those replies from the cache and the server stays off. Resource subscriptions and the log level, which Cursor and VS Code send on connect, are taken by mcp-nap and handed to the server when it starts. The first other request, usually a tool call, starts it. It stops again after 10 minutes with nothing in flight.
If the server's command or its entry script changes, the cache is refilled on the next start. If the lists change anyway, mcp-nap sends list_changed and the client refetches.
What sleeping costs
- The first call after a stop waits for the server to start, about half a second for the npx servers above.
- No completions while asleep:
completion/completegets an empty list until something wakes the server. - No resource updates while asleep. Subscriptions are kept and passed on at the next start, but nothing is running to notice a change in between.
- State the server holds dies at the stop, below.
Servers that keep state
A server that holds state between calls loses it when it stops. Playwright's open browser is the common one. Keep those running for the life of the session with --idle 0:
mcp-nap unwrap playwright && mcp-nap wrap playwright --idle 0
--idle N sets any other timeout in seconds.
Servers whose login expires
Some servers keep an OAuth token that dies on a schedule, and every call then fails with invalid_grant until you run the server's own login command. --reauth ARG does that for you: on such a failure it runs <command> ARG, opens the first https URL it prints, and restarts the server once the login exits cleanly. wrap doesn't set it, so add it by hand:
"google-docs": {
"command": "mcp-nap",
"args": ["google-docs", "--reauth", "auth", "--", "google-docs-mcp"]
}
Undo
mcp-nap unwrap # or: unwrap --client cursor, unwrap --client vscode
That puts every wrapped server back as it was. Env edits you made to a wrapped entry after wrap are kept. Or quit the client and copy the backup back over the config. wrap printed its path; it sits next to the config as .claude.json.mcp-nap-<date>-<time> or mcp.json.mcp-nap-<date>-<time>.
http and sse servers
They are left alone in every client. For Claude Code, mcp-nap edits the config through claude mcp remove and claude mcp add-json, because live sessions write ~/.claude.json too, and removing an http or sse server would also delete its OAuth login. Re-adding a server moves it to the end of the list, so if an http server sits between stdio servers, the stdio servers after it end up after it in the file. wrap prints a note when that happens. The order doesn't change how Claude Code runs them.
Limits
- macOS, Linux and Windows. The tables above are from macOS. On Linux (a Debian container, node 22, Python 3.11) the tests pass and one
bench/measure.py --sessions 1 --reps 1run gave 841 MB bare against 42 MB withuv tool install. - On Windows 11 (arm64, Python 3.9 and 3.13, node 22) the tests pass, and a wrapped
npxfilesystem server starts on the first tool call and leaves nocmd.exeornode.exebehind after the idle stop, after the session closes, or after the wrapper is killed. Not yet tried there:wrapagainst a real Claude Code install, and Claude Code starting themcp-napconsole script. Ifclaudeis npm'sclaude.cmd, cmd.exe may expand a%NAME%inside an env value aswrappasses it through. --client cursorand--client vscodewere run against the real apps on macOS only. Their tests pass on Linux and Windows too.- Stdio servers only.
- Without
--client,wrapneeds theclaudeCLI on PATH. - Without
--client,wrapandunwrappass each server's entry, env values included, toclaude mcp add-jsonas a command-line argument. For about a second per server, another user on the same machine can read it inps.
MIT licence.
Metadata
Release files for mcp-nap 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_nap-0.2.0.tar.gz | 31.5 kB | Without provenance | Details for mcp_nap-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_nap-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_nap-0.2.0-py3-none-any.whl |
Total release size: 48.5 kB
Release files / mcp_nap-0.2.0.tar.gz
| Download URL | mcp_nap-0.2.0.tar.gz |
|---|---|
| Size | 31.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1d25c39cfa74b6e43e820b48aa038b2e1f330c8af6cf3669d0d1c6fdb31fe084
|
|
BLAKE2b-256 checksum How to use checksums |
2113a189237aa80dd4fa1a8a1ff583f3b05d8d5f15add2954d4f3cbfd3273755
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / mcp_nap-0.2.0-py3-none-any.whl
| Download URL | mcp_nap-0.2.0-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bb269edfe9c6159b55d89ac638345a1aa2019b7b25759a0cc52185322b56e481
|
|
BLAKE2b-256 checksum How to use checksums |
ef4f16f6fa87520fc52cb7fd9b018484f1c65e407822bb0ad74950299b473b6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for mcp-nap 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.