sharedoc-mcp
Agent-generated Markdown → a link you can hand to anyone. GitHub gists today, your own server tomorrow.
English | 繁體中文
An MCP stdio server — works in Claude Code, Codex CLI, and any MCP client — that gives your agent 9 tools to publish, update, search, and revoke shareable documents. Two pluggable backends behind one interface: gist (zero setup, rides your logged-in gh CLI) and selfhost (SQLite on your machine, passwords, enforced expiry).
When a backend can't honor a parameter (e.g.
passwordon gist), it returns a clear error instead of silently ignoring it.
Why?
AI agents produce Markdown constantly — reports, research digests, meeting notes. Getting that to another human usually means copy-pasting walls of text into a chat window.
Without sharedoc-mcp With sharedoc-mcp
──────────────────── ─────────────────
copy a wall of text into chat "share this as a doc"
paste again for each person one link for everyone
content lives in chat scroll revoke / extend / append later
"can you password it?" …no selfhost backend: bcrypt + expiry
Where do those Markdown digests come from? Often another skill — e.g. audio-tldr turns videos and podcasts into Markdown digests; sharedoc-mcp turns them into links.
Features
- ✓ 9 MCP tools: create / append / update content / extend / reset password / rename / revoke / delete / search
- ✓
sharedoc-mcp servedaemon mode — selfhost links keep working after your MCP client closes - ✓ Content search: find old share links by what's in them, not just the title
- ✓
GET /healthz— identity-aware health probe for external monitoring / restart automation - ✓ Two backends, one interface — switch with a single env var, tool schemas stay identical
- ✓ Gist backend (default): secret gists via your logged-in
ghCLI — no tokens to manage, nothing new to host - ✓ Selfhost backend: docs stay on your machine (SQLite via built-in
node:sqlite— zero native modules) - ✓ Server-verified passwords (bcrypt) with rate-limited attempts — 5/minute, HTTP 429, counters persisted in SQLite so a restart can't reset them (selfhost)
- ✓ Enforced expiry (410) and revoke with a 7-day content-purge grace (selfhost); lazy expiry cleanup (gist)
- ✓ Markdown rendered through
marked+sanitize-html— scripts, event handlers, andjavascript:URLs in shared content are stripped - ✓ Viewer binds 127.0.0.1 only, answers with a strict security-header set (CSP
default-src 'none', nosniff, DENY framing, no-referrer, no-store) — exposure is a tunnel you control (recipes below) - ✓ Local index for
search_shared_docs+ create dedup (identical unprotected retries within 5 min return the same URL; a retry that adds a password/expiry always creates a new doc) - ✓
search_shared_docssupports offset pagination (hasMorein the response) and, on selfhost, view stats (viewCount/lastViewedAt, counted on a successful render only) - ✓ Docker one-liner for the standalone
servedaemon, defaults to the same 127.0.0.1-only binding as everywhere else - ✓ Two MCP clients can share one data dir: SQLite WAL + busy timeout, graceful port sharing
- ✓ 110 offline tests;
npm testpasses on a clean checkout
Install
Requires Node.js ≥ 22.13.0. Gist backend additionally needs GitHub CLI logged in (gh auth login).
Option A — Claude Code (one line):
claude mcp add sharedoc --scope user -- npx -y sharedoc-mcp@^2
Option B — Codex CLI (~/.codex/config.toml):
[mcp_servers.sharedoc]
command = "npx"
args = ["-y", "sharedoc-mcp@^2"]
Option C — Cursor (one click): hit Add to Cursor, or merge into ~/.cursor/mcp.json:
{ "mcpServers": { "sharedoc": { "command": "npx", "args": ["-y", "sharedoc-mcp@^2"] } } }
Option D — VS Code (one click): hit Install in VS Code, or from a terminal:
code --add-mcp '{"name":"sharedoc","command":"npx","args":["-y","sharedoc-mcp@^2"]}'
Option E — any other MCP client: run npx -y sharedoc-mcp@^2 as a stdio server.
Why
@^2? A barenpx -y sharedoc-mcpresolves the latest published version on every cold start — a future 3.0 could change behavior (or remove a tool) under you without warning.@^2follows 2.x fixes but never crosses a breaking major; pin an exact version (@2.2.0) if you want zero drift.
Pick your backend
Gist quickstart
Ask your agent to "share this as a doc" — it calls create_shared_doc and returns a secret gist URL. Secret gists are not listed publicly and the URL is unguessable, but anyone who has the link can read it — that's the whole security model of this backend. Need passwords? Use selfhost.
A local index (~/.config/sharedoc-mcp/index.json) tracks what you've shared, powering search and expiry cleanup. Expiry here is lazy: expired gists are deleted the next time any tool runs, not at the exact expiry moment.
Selfhost quickstart
claude mcp add sharedoc --scope user --env SHAREDOC_BACKEND=selfhost -- npx -y sharedoc-mcp@^2
Docs live in SQLite at ~/.local/share/sharedoc-mcp/; a viewer serves them at http://127.0.0.1:8377. To share beyond your machine, put a tunnel in front and set SHAREDOC_PUBLIC_URL:
Links that outlive your editor: in MCP mode the viewer dies with the MCP client — close Claude Code and selfhost links stop answering until the next session (data is safe in SQLite). Run the standalone daemon to keep links alive around the clock:
npx -y sharedoc-mcp@^2 serve # viewer only, same DB — keep it running via launchd/systemd/tmux (Windows: Task Scheduler or NSSM)MCP clients detect the daemon already owns the port and simply use it.
When to set this up: the moment you first hand a link to someone else — do it together with your tunnel (both should be long-running, e.g. under launchd/systemd). Until then the MCP-mode viewer is enough, and gist-backend users never need it.
Own a domain? Cloudflare named tunnel, step by step
A branded, stable share URL like https://docs.example.com/docs/<uuid> — TLS handled by Cloudflare, works from behind NAT:
# one-time setup (domain already added to Cloudflare — the free plan is enough)
cloudflared tunnel login
cloudflared tunnel create sharedoc
cloudflared tunnel route dns sharedoc docs.example.com
~/.cloudflared/config.yml:
tunnel: sharedoc
credentials-file: ~/.cloudflared/<tunnel-id>.json
ingress:
- hostname: docs.example.com
service: http://127.0.0.1:8377
- service: http_status:404
Run cloudflared tunnel run sharedoc (or install it as a service for always-on), and register the MCP server with the public URL:
claude mcp add sharedoc --scope user \
--env SHAREDOC_BACKEND=selfhost \
--env SHAREDOC_PUBLIC_URL=https://docs.example.com \
-- npx -y sharedoc-mcp
Extras this unlocks: Cloudflare's DDoS protection comes free; you can layer WAF rules, or put Cloudflare Access (SSO) in front of everything except the share paths — an "SSO inside, password-protected shares outside" split.
Alternative — always-on without a home machine: run sharedoc-mcp on a VPS (where your agent also runs) and point nginx/caddy at 127.0.0.1:8377 with your domain and auto-TLS; no tunnel needed.
Docker
Runs the same standalone serve daemon as above, in a container:
docker build -t sharedoc-mcp .
docker run -d --name sharedoc \
-p 8377:8377 \
-e SHAREDOC_BIND_HOST=0.0.0.0 \
-v sharedoc-data:/data \
sharedoc-mcp
-v sharedoc-data:/datapersistsdocs.dbin a named volume — recreating the container keeps your docs.SHAREDOC_BIND_HOST=0.0.0.0is required to reach the container at all. The viewer binds127.0.0.1by default — same as every other deployment in this README — and inside a container that's unreachable throughdocker run -p, because-pforwards to the container's network interface, not its loopback. Without this env var,docker logswill show the viewer listening, but the mapped host port will refuse every connection.- Setting it to
0.0.0.0means any process that can reach the container's exposed port reaches the viewer, unauthenticated by network position — the same exposure tradeoff as running any other unauthenticated app in a container without a proxy in front. Put it behind the same kind of front door as any other selfhost recipe above (a reverse proxy on the host, a Tailscale sidecar, a Cloudflare tunnel) rather than publishing-p 8377:8377straight to the internet. Password-protecting individual docs (this backend's built-in feature) is not a substitute for that. - If the address recipients will use differs from
http://<host>:8377(a reverse proxy, a domain, a tunnel), setSHAREDOC_PUBLIC_URLtoo — the container has no way to infer it. - The MCP stdio server itself isn't meant to run in Docker — it needs a local process wired to an MCP client's stdin/stdout. Point your MCP client at
npx -y sharedoc-mcpon the host as usual; only the standalone viewer daemon belongs in the container.
Environment variables:
The 9 tools
Privacy
Data flow, by backend:
- Gist backend: your document content is uploaded to GitHub as a secret gist under your account — GitHub's terms and retention apply. The local index stays in
~/.config/sharedoc-mcp/— it stores titles, URLs, timestamps, and the first 200 characters of each doc (for local content search); never the full content. Nothing is sent anywhere except GitHub via your ownghCLI. - Selfhost backend: content never leaves your machine unless you attach a tunnel — then it's served to whoever you gave the link (and the tunnel provider relays the traffic). Passwords are stored only as bcrypt hashes.
- sharedoc-mcp itself has no telemetry and calls no third-party service of its own.
Security semantics, honestly
- Gist links are bearer tokens: anyone with the URL reads the doc. Revoke deletes the gist immediately and irreversibly.
- Selfhost passwords are verified server-side before content is served; only WRONG attempts are rate-limited (5/minute per source+doc; a correct unlock clears the counter), with counters persisted in SQLite — restarting the server does not reset them. Behind a tunnel, all external visitors share one source address, so the practical limit is 5/minute per doc — stricter than per-visitor; one person mistyping can briefly lock a doc for others.
- There is deliberately no file-sharing tool: an arbitrary-path "share this file" tool is a prompt-injection exfiltration vector (
.env, keys) — a hijacked agent could publish secrets. Removed rather than allowlisted. - The viewer never binds beyond 127.0.0.1. Whether and how it reaches the internet is entirely your tunnel's configuration.
Develop
git clone https://github.com/AugustusW/sharedoc-mcp.git
cd sharedoc-mcp
npm install
npm test # builds, then runs 110 offline tests — gh CLI is mocked, HTTP tests hit 127.0.0.1 only
Versioning: every release bumps version in package.json, adds a CHANGELOG entry, and is published as a git tag + GitHub Release + npm.
To get update notifications: Watch this repo (Custom → Releases). npx -y fetches the latest published version on each cold run; your index and docs DB live outside the package — updating never touches them.
Status
v2.2.0 (CHANGELOG) — core logic is covered by 110 offline unit/integration tests (the gh CLI is mocked; HTTP tests run against 127.0.0.1 only; no network needed). The full flows have been manually verified (2026-07-25: real secret-gist create/index/delete via the built server over stdio JSON-RPC, and the selfhost password flow end-to-end — form → wrong password 401 → correct password 200 → rate-limit 429 → revoke 410 — plus lsof confirmation of the 127.0.0.1-only bind) on:
- macOS (Apple Silicon), Node v25 — gist + selfhost backends
Tunnel recipes are documented from the tools' standard behavior; Windows/Linux and real-tunnel end-to-end runs have not yet been verified — reports welcome. The manual pass above predates 2.2.0: its additions (update_shared_doc_content, view stats, pagination, Docker) are covered by the test suite but have not had an equivalent hands-on run.
License
MIT © AugustusW
