stapler MCP server
Commit Nov 13, 2026Reduces memory bloat by running MCP servers as a single shared daemon with thin-client proxies for multiple AI agent sessions.
Also known as tstapler/stapler-mcp
- Stars
- 0
- Tools
- 19
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is stapler MCP?
stapler reduces memory bloat by running MCP servers as a single shared daemon with thin-client proxies for multiple AI agent sessions. It exposes 19 tools, such as fetch_page, brave_web_search, read_website.
Summary generated from the project's README
About stapler MCP server
Developers using Claude Code or other AI agent sessions can reduce memory bloat and disk usage by using stapler-mcp to run multiple MCP servers as a single shared daemon. Instead of every subagent spawning its own heavy process and duplicating tool installs, this system uses a thin-client architecture where a single background process manages the heavyweight state, including browser pools and caches. This prevents the massive memory overhead and redundant cache files often caused by running tools via npx or uvx.
Users can connect through a standard stdio thin client that automatically manages the daemon via a Unix domain socket, or they can opt into a Streamable HTTP endpoint. The HTTP transport is protected by a bearer token and allows clients to connect directly to the daemon, bypassing subprocesses entirely. The server is written in Rust and can be deployed as a native CLI or a zero-native-binary npx package, making it compatible with various environments while maintaining a single machine-wide instance.
What you can do with it
- 1Reduce memory bloat in agent treesPrevent multiple subagents from spawning independent, heavy process trees for the same tools.
- 2Connect via HTTP transportAllow MCP-over-HTTP clients to communicate directly with the daemon without using a subprocess.
- 3Run as a persistent serviceEnsure the MCP daemon survives reboots by setting it up as a systemd or launchd service.
Written from the project's README. Every use case is checked against a quote from it.
stapler MCP tools 19
Detected from the READMEfetch_pagebrave_web_searchread_websiteread_saved_pagedownload_websitestapler_browser_close_sessionstapler_browser_tabsstapler_browser_hoverstapler_browser_select_optionstapler_browser_press_keystapler_browser_wait_forstapler_browser_list_sessions
Show all 19 toolsShow fewer tools
stapler_browser_close_all_sessionsstapler_daemon_statuswebbrowser-corebrowser-advanceddocsdaemon
Configuration
STAPLER_MCP_BROWSER_PROFILE_DIRSTAPLER_MCP_TOOL_PROFILE
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletstapler/stapler-mcp is public and reachablegithub.com/tstapler/stapler-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/tstapler/stapler-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model19 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubstapler-mcp
A from-scratch reimplementation of several third-party MCP (Model Context
Protocol) servers this user previously ran per-session via npx/uvx. Those
tools were causing severe memory bloat: every subagent in a Claude Code
session independently spawned its own full copy of every MCP server
(confirmed via pstree on a live 9-subagent tree — 9 separate process trees
for the same tools), and npx/uvx each pay 60-100MB of cold-resolve
wrapper overhead per launch on top of the real server. One tool in
particular (mcp-website-downloader, invoked via uvx --from git+...) left
40+ fully-duplicated installs in ~/.cache/uv (9.7GB) because uvx
re-resolves per invocation instead of reusing a cached environment.
Originally a Go implementation; rewritten in Rust so the same core logic can
ship two ways — a native CLI and a zero-native-binary npx package — without
duplicating the thin-client/daemon architecture or the tool logic twice. See
NOTES.md for the phase-by-phase build log and what's deferred.
Architecture: thin client + shared daemon, two transports
This is the entire point of the project, not an optional nicety. The shared daemon is reachable two ways: the default per-session stdio thin client (unchanged), and an opt-in Streamable HTTP endpoint for clients that can speak MCP-over-HTTP directly and skip the per-session subprocess entirely.
Claude Code session 1 ──▶ stapler-mcp (thin stdio MCP server) ─┐
Claude Code session 2 ──▶ stapler-mcp (thin stdio MCP server) ─┼──▶ ~/.stapler-mcp/daemon.sock ──▶ stapler-mcp-daemon
Claude Code subagent N ─▶ stapler-mcp (thin stdio MCP server) ─┘ (one process, one browser pool,
one HTTP client, one cache —
Any MCP-over-HTTP client ─────────────────────────────────────────────▶ 127.0.0.1:$STAPLER_MCP_HTTP_PORT/mcp
shared machine-wide, same daemon,
bearer-token authenticated)
- thin client (no flags) — what Claude Code actually launches per
session as the MCP server. On startup it checks whether the daemon is
already reachable at
~/.stapler-mcp/daemon.sock; if not, it spawns--daemondetached and waits for it to become ready. Every tool call is then proxied over that Unix socket and the result streamed back over stdio. This process holds no heavyweight state of its own. --daemon— the long-running background process that owns the actual heavyweight state (headless browser pool, HTTP clients, caches). Exactly one instance runs machine-wide. If several thin clients race to auto-start it simultaneously, every spawned process independently attempts an exclusive lock on~/.stapler-mcp/daemon.lock— only the winner binds the socket, the rest see "already running" and exit immediately (crates/native/src/lock.rs/crates/wasm/src/glue/lock.js).- HTTP transport (opt-in, via
STAPLER_MCP_HTTP_PORT) — the same--daemonprocess also binds127.0.0.1:$STAPLER_MCP_HTTP_PORT/mcpas a Streamable HTTP MCP endpoint, protected by a bearer token the daemon generates on first HTTP-enabled startup (~/.stapler-mcp/http-token, mode0600). A client that speaks MCP-over-HTTP natively connects straight to the daemon — no per-session thin-client subprocess at all. The stdio thin client keeps working unchanged alongside it; the two transports share the same daemon, browser pool, and caches. See "First time enabling HTTP" below to configure a client for this.
This mirrors a fix already underway in the sibling project stapler-squad
(also owned by this user), where its own --mcp subcommand is moving from
"duplicate the whole backend per subagent" to "thin client of the one
already-running service" — same pattern, different transport. stapler-mcp
is an independent repository and does not depend on or modify stapler-squad.
Running as a persistent service
Running --daemon as a supervised, auto-restarting user service means it
survives reboots and doesn't depend on a thin client happening to auto-spawn
it first. Templates for both platforms live in scripts/.
Linux (systemd user service) — scripts/stapler-mcp.service.example:
cp scripts/stapler-mcp.service.example ~/.config/systemd/user/stapler-mcp.service
# edit STAPLER_MCP_HTTP_PORT / ExecStart path as needed, then:
systemctl --user daemon-reload
systemctl --user enable --now stapler-mcp
stapler-mcp --status
macOS (launchd agent) — scripts/com.tstapler.stapler-mcp.plist.example:
cp scripts/com.tstapler.stapler-mcp.plist.example ~/Library/LaunchAgents/com.tstapler.stapler-mcp.plist
# edit the ProgramArguments path (launchd does not expand ~/$HOME) and
# STAPLER_MCP_HTTP_PORT as needed, then:
launchctl load -w ~/Library/LaunchAgents/com.tstapler.stapler-mcp.plist
stapler-mcp --status
Redeploying the latest version
Two processes need updating: the per-session thin client and the shared daemon. The daemon is not replaced automatically, so a stale one keeps serving the old code after a rebuild.
git checkout main && git pull
# Build in-repo (what a `command` pointing at ./target/release/stapler-mcp runs).
# Separate invocations: building both together links the heavy deps into the thin client.
cargo build --release --locked -p stapler-mcp-daemon # ~4 min cold
cargo build --release --locked -p stapler-mcp # thin client, ~2 MB
# Or install both beside each other in ~/.cargo/bin instead:
# scripts/install.sh # downloads the prebuilt release if one exists for this platform,
# # else builds from source with the faster `release-fast` profile
# # (STAPLER_MCP_FROM_SOURCE=1 to force a build, STAPLER_MCP_PROFILE=release
# # for the fat-LTO build). Releases come from pushing a `v*` tag.
# Restart the daemon so it picks up the new binary:
systemctl --user restart stapler-mcp # if the service unit is installed
# otherwise:
pkill -f 'stapler-mcp-daemon|stapler-mcp --daemon'
stapler-mcp --status # never auto-spawns; "not running" is expected here
# next tool call spawns the new daemon, or start it now:
# setsid nohup stapler-mcp-daemon >/dev/null 2>&1 &
stapler-mcp --status # expect: daemon: running (pid ...)
If you run from the repo build rather than ~/.cargo/bin, point the unit at it
after copying the example: ExecStart=%h/Programming/stapler-mcp/target/release/stapler-mcp-daemon.
With the HTTP transport registered in ~/.claude.json (see "First time enabling
HTTP"), sessions connect straight to the daemon with no thin-client subprocess,
so a systemctl --user restart stapler-mcp is the whole redeploy.
Already-running Claude Code sessions keep their old thin-client process until
restarted; restart the session (or /mcp reconnect) to pick up the new binary.
Use the stapler-mcp that your MCP client config points at — --status from
another copy on PATH reports the same daemon, but the thin client it execs
may be an older build.
Troubleshooting
Work through these in order:
- Is the service unit running?
systemctl --user status stapler-mcp(Linux) orlaunchctl print gui/$(id -u)/com.tstapler.stapler-mcp(macOS). - Is the daemon itself reachable?
stapler-mcp --status— reports the daemon's PID and, separately, whether its HTTP transport is configured and listening. This never auto-spawns a daemon, so a clean "not running" is a real diagnosis, not a side effect. - Start it.
systemctl --user start stapler-mcpif a service unit is installed (step 1), otherwisestapler-mcp --daemondirectly.
Falling back to stdio: if the HTTP transport is misbehaving and you just
need things working again, revert your MCP client config's stapler-mcp entry
back to the plain stdio form — command/args pointing at the
stapler-mcp binary with no STAPLER_MCP_HTTP_PORT involved. The stdio
thin-client path doesn't depend on the HTTP transport at all.
First time enabling HTTP
- Start the daemon with the HTTP port set:
STAPLER_MCP_HTTP_PORT=47439 stapler-mcp --daemon - On that first HTTP-enabled startup it generates a bearer token at
~/.stapler-mcp/http-token(mode0600) and logs that it did so. - Run
stapler-mcp --print-configto print the ready-to-use client config block (see "Distributing the HTTP token" below for where it reads from and why it never invents a token). - Paste the result into
~/.claude.json's user-scopedmcpServersentry — after running the verification snippet below to confirm that file isn't git-tracked. - Optionally install the persistent service (above) so the daemon survives reboots instead of depending on a thin client auto-spawning it.
- Verify with
stapler-mcp --status— expectdaemon: running (pid ...)andhttp: listening on 127.0.0.1:47439.
Distributing the HTTP token
Never paste a literal bearer token into the git-tracked mcp-servers.json
(or any file in this repo). Instead, run stapler-mcp --print-config and
paste its output into ~/.claude.json — Claude Code's real documented
user-level MCP config file. That's a standalone file directly in $HOME,
distinct from ~/.claude/ (which may itself be a dotfiles-managed git
symlink on some machines) — the two are easy to confuse, so verify which one
you're editing before pasting a secret into it:
target=$(readlink -f ~/.claude.json); repo=$(readlink -f ~/dotfiles)
case "$target" in
"$repo"/*) git -C "$repo" ls-files --error-unmatch -- "${target#$repo/}" \
&& echo "TRACKED — unsafe, gitignore it or use headersHelper instead" \
|| echo "inside the repo dir but untracked — safe for now" ;;
*) echo "outside the repo dir entirely — cannot be tracked, safe" ;;
esac
${ENV_VAR} substitution inside a headers field has been reported
unreliable in Claude Code and isn't a safe substitute for this manual
copy-paste approach — paste the real token from --print-config, don't try
to reference it indirectly.
Why a Unix domain socket
Simple, fast, local-only, no port-conflict risk across concurrent sessions. Liveness/single-instance is a lockfile, not "is the socket file present" (stale sockets from a crashed daemon are safe to unlink once a new daemon holds the lock).
Two distributions, one core
The actual logic (protocol framing, EnsureDaemon state machine, tool
business logic) lives once in crates/core — a #![no OS calls] crate whose
only OS-touching surface is a set of trait "ports" (crates/core/src/ports.rs):
socket, process lock, process spawn, HTTP, browser, file store, env, clock.
Two adapters implement those ports:
crates/native + crates/cli |
crates/wasm + npm/ |
|
|---|---|---|
| Target | native binary (cargo install) |
wasm32-unknown-unknown compiled to WASM, run inside Node |
| Socket/lock/spawn | tokio, std::fs::File::try_lock, std::process::Command |
Node net/fs.mkdirSync/child_process, called from Rust via wasm-bindgen JS imports |
| HTTP | reqwest |
Node's built-in fetch |
| Browser automation | chromiumoxide (drives system Chrome over CDP) |
playwright-core with channel: "chrome" (system Chrome, no download) |
| MCP stdio transport | rmcp (official Rust SDK) |
@modelcontextprotocol/sdk (official TS SDK, low-level Server API) |
| Why | full native performance/control, no Node dependency | npx-installable with zero native binary — nothing for macOS Gatekeeper to block, since the package ships pure .wasm + JS, not a downloaded executable |
Both adapters speak the identical wire protocol and are interoperable on
the same machine: a native daemon will happily answer a Node thin client
and vice versa (verified in crates/cli/tests/daemon_ping.rs and
npm/test/e2e.test.js, and manually cross-checked in both directions during
development). Thin clients only ever care whether ping succeeds — never
which implementation is on the other end.
Tool input/output schemas are derived once (via schemars on shared types in
crates/core/src/schema.rs) and reused by both the native rmcp tool
registration and a wasm-exported list_tools_json() the Node side serves
verbatim — never hand-authored twice.
Tools implemented
| Tool | Notes |
|---|---|
fetch_page |
Headless-render a URL, return title + extracted text, optionally save rendered HTML to a local path (savePath). |
brave_web_search |
Stateless HTTP wrapper over the Brave Search API. Reads BRAVE_API_KEY from the daemon's environment. Base URL overridable via BRAVE_API_BASE_URL (used by both adapters' test suites to point at a mock server). |
read_website |
Fetch a URL (optionally BFS-crawling same-host links up to maxDepth/maxPages), extract main content via Readability-style extraction, return it as Markdown. Cached by URL hash on the daemon — a cache hit skips the network fetch entirely (at the cost of not expanding that page's links further). Respects robots.txt. Once the combined Markdown across every page returned passes ~60,000 characters (tunable via maxInlineChars, or force it for every page with alwaysSaveToFile), further pages come back as a short preview plus savedPath instead of the full text, so a long crawl can't crowd out the rest of the caller's context. |
read_saved_page |
Search (query, with contextLines of surrounding context — like grep -n -C) or paginate (offset/limit, line-numbered — like Read) a page previously saved by read_website's savedPath. Only ever reads a path matching that mechanism's own naming scheme, never an arbitrary file. Works even when the caller isn't on the same machine as the daemon. |
download_website |
Same crawl/robots.txt mechanics as read_website, saves raw HTML per page under saveDir instead of extracting Markdown. Merges what were two separate third-party MCP servers this user ran before. |
stapler_index_docs / stapler_search_docs / stapler_list_indexed_sources / stapler_remove_indexed_source |
Native-only: crawl a doc site, embed it locally (fastembed/all-MiniLM-L6-v2), and semantically search it — a narrower-scope, in-process replacement for the Node docs-mcp-server. stapler_-prefixed to avoid a tool-name collision with that server's own search_docs. |
stapler_browser_navigate / stapler_browser_click / stapler_browser_type / stapler_browser_snapshot |
playwright-mcp-style browser automation via accessibility-tree snapshots, with a sessionId threaded across calls and a 300s idle-timeout reaper for abandoned sessions. Snapshots include open shadow DOM content automatically, and recursively traverse same-process (same-origin) <iframe> content up to 5 levels deep by resolving each Iframe node's child frame via CDP and splicing in its AX tree; cross-origin iframes run in a separate renderer process this session can't reach, so they're left as childless Iframe leaves (#20). |
stapler_browser_close_session |
Close a browser session and release its resources ahead of the idle-timeout reaper. |
stapler_browser_tabs |
List/open/switch/close tabs within a session via an action field (list/new/select/close), mirroring @playwright/mcp's browser_tabs. |
stapler_browser_hover |
Hover the pointer over an element identified by a snapshot ref, for triggering hover-revealed UI. |
stapler_browser_select_option |
Select one or more options in a <select> element identified by a snapshot ref. |
stapler_browser_press_key |
Press a single keyboard key, optionally focusing an element by ref first. |
stapler_browser_wait_for |
Wait until given text appears/disappears and/or a minimum time elapses before returning the next snapshot. |
stapler_browser_list_sessions |
List all open sessions daemon-wide (session id, tab count, idle time in milliseconds, and blocked/crashed diagnostic flags) — useful for finding sessions leaked by a crashed subagent. |
stapler_browser_close_all_sessions |
Close every open session daemon-wide and report which succeeded/failed. Closes are attempted concurrently so one wedged session doesn't block the rest. No per-caller scoping: this closes sessions daemon-wide regardless of which caller opened them — safe for a single-agent daemon, but a multi-tenant daemon would need real authorization before exposing it. |
stapler_daemon_status |
Report daemon-wide status not tied to any one session — currently the active browser profile persistence mode (ephemeral or persistent at <path>) and, if set, an unsafe-location warning. See "Persistent browser profile" below. |
All tools are verified end-to-end against real dependencies (a real headless
Chrome, a real mock/live HTTP server) rather than mocked ports — on both
adapters, except docs-index, which is native-only. See
NOTES.md for the phase-by-phase verification detail and the
real bugs each round of testing found.
Persistent browser profile
By default, every browser session opened during one daemon's lifetime already
shares a single Chrome profile (cookies, login state) — that's unaffected by
this section. What doesn't survive by default is a daemon restart: each
new daemon process launches Chrome against a fresh, ephemeral
user_data_dir, so cookies/login state are lost on upgrade, crash, or reboot.
To make that survive a restart, set STAPLER_MCP_BROWSER_PROFILE_DIR to an
absolute path (a leading ~/ is expanded) in the daemon's environment
before starting it:
STAPLER_MCP_BROWSER_PROFILE_DIR=~/.stapler-mcp/browser-profile stapler-mcp --daemon
This is a daemon-startup-only setting, not a per-call stapler_browser_navigate
parameter — user_data_dir is a Chrome launch-time flag consumed once, before
any session exists. Leaving the variable unset, empty, or set to a relative
path falls back to today's ephemeral behavior (a warning is logged for a
rejected relative path). The directory is chmod'd 0700 on Unix; a
non-blocking warning is logged (and surfaced via stapler_daemon_status /
--status below) if its resolved path looks like it's inside a git
repository or a cloud-synced folder (Dropbox/iCloud Drive/Syncthing) — this
directory holds near-plaintext browser credentials. A second daemon pointed
at the same directory fails to launch with an error naming the directory and
the likely cause (SingletonLock collision) rather than raw chromiumoxide
error text.
Verify whether persistence is actually active — without reading
daemon.log — via the stapler_daemon_status MCP tool or:
stapler-mcp --status
Selectable tool profiles
By default every tool above is registered on every connection — a session
that only ever calls read_website still pays the tools/list
context cost of the full browser-automation and docs-index surface. Set
STAPLER_MCP_TOOL_PROFILE to a comma-separated list of categories to narrow
what a session sees and can call:
STAPLER_MCP_TOOL_PROFILE=web,docs stapler-mcp
Where to set it depends on the transport. For stdio, the profile is
per-session: each thin-client process reads its own environment, so
different Claude Code sessions can run different profiles. For HTTP,
McpRouter::with_transport builds a fresh router per HTTP session, but it
reads the env var from the long-lived --daemon process's own environment —
fixed once at daemon startup and identical for every HTTP session and bearer
token holder. Set it in the daemon's launch environment for HTTP, not an
individual HTTP client's; there's no way to give two HTTP callers of the
same daemon different profiles.
| Category | Tools |
|---|---|
web |
fetch_page, brave_web_search, browser_web_search, read_website, read_saved_page, download_website |
browser-core |
stapler_browser_navigate, stapler_browser_click, stapler_browser_type, stapler_browser_snapshot, stapler_browser_close_session, stapler_browser_close_all_sessions, stapler_browser_list_sessions, stapler_browser_tabs |
browser-advanced |
stapler_browser_type_secret, stapler_browser_hover, stapler_browser_select_option, stapler_browser_press_key, stapler_browser_wait_for, stapler_browser_screenshot, stapler_browser_pdf, stapler_browser_evaluate, stapler_browser_get_html, stapler_browser_fill_form, stapler_browser_set_checked, stapler_browser_history, stapler_browser_resize, stapler_browser_find |
docs |
stapler_index_docs, stapler_search_docs, stapler_list_indexed_sources, stapler_remove_indexed_source |
daemon |
stapler_daemon_status |
Leaving the variable unset, empty, or set to all keeps today's behavior
(every tool registered). An unknown category token is logged and ignored; if
every token in a non-empty value is unknown, the whole thing falls back to
all rather than silently disabling every tool. A disabled tool is hidden
from tools/list and rejected by tools/call with the standard "tool not
found" error, not merely undocumented.
This is a context-size optimization, not a security control. It only changes which tools this one router instance exposes — it does nothing to stop another process, session, or (on HTTP) another holder of the same bearer token from invoking the full tool set against the same shared daemon, which has no per-caller authorization model. Don't rely on a profile to contain an untrusted or compromised caller.
Deferred
See NOTES.md for the full log. Wiring wasm/npm packaging
into CI (#8) and the
wasm HTTP adapter not capturing final_url on redirect
(#9) are both closed —
CI now builds npm/pkg/ via wasm-bindgen and runs npm test on every
push, and the fix landed in crates/wasm/src/glue/http.js. Publishing the
npm package to the public registry remains deliberately undone (needs
explicit sign-off + credentials; npm/package.json keeps "private": true
as a guard). The one still-open item is whether docs-index's deliberately
narrow scope (Markdown/HTML only, one local embedding model, brute-force
cosine search) is ever worth widening
(#10) — "no action
yet."
Usage
Native
# Two binaries: the per-session thin client and the shared daemon. They must sit
# in the same directory — the thin client auto-starts the `stapler-mcp-daemon`
# beside it. Build the thin client alone with `-p stapler-mcp` (selecting the
# daemon in the same cargo invocation links its browser/embedder deps into it).
cargo build -p stapler-mcp # target/debug/stapler-mcp (thin client)
cargo build -p stapler-mcp-daemon # target/debug/stapler-mcp-daemon
cargo build --profile release-thin -p stapler-mcp # smallest thin client (~2.7 MB)
# Or install both into one directory (cargo install takes one package per call):
scripts/install.sh
# What Claude Code should register as the MCP server command:
./target/debug/stapler-mcp
# Manual daemon inspection (normally auto-started, not run by hand):
./target/debug/stapler-mcp-daemon
# `stapler-mcp --daemon` still works: the thin client execs the sibling daemon.
# Read-only diagnostics — never auto-spawn a daemon (the thin client execs the
# sibling daemon binary, which implements them):
./target/debug/stapler-mcp --status # daemon/HTTP liveness
./target/debug/stapler-mcp --print-config # HTTP client config block, see "First time enabling HTTP"
stapler MCP questions
What tools does stapler MCP provide?
It exposes 19 tools, including fetch_page, brave_web_search, read_website, read_saved_page, download_website.
Can I run this as a persistent background service?
Yes, it provides templates for Linux (systemd user service) and macOS (launchd agent) to ensure the daemon survives reboots.
Does it support HTTP transport?
Yes, it offers an opt-in Streamable HTTP endpoint protected by a bearer token for clients that can speak MCP-over-HTTP directly.
How do I update the server?
You must update both the thin client and the daemon separately, as the daemon is not replaced automatically during a rebuild.