Sharedoc MCP

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. password on 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 serve daemon 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 gh CLI — 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, and javascript: 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_docs supports offset pagination (hasMore in the response) and, on selfhost, view stats (viewCount/lastViewedAt, counted on a successful render only)
• ✓ Docker one-liner for the standalone serve daemon, 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 test passes 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 bare npx -y sharedoc-mcp resolves the latest published version on every cold start — a future 3.0 could change behavior (or remove a tool) under you without warning. @^2 follows 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:

`bash

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/ — 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/ .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:/data persists docs.db in a named volume — recreating the container keeps your docs.
• `SHAREDOC_BIND_HOST=0.0.0.0` is required to reach the container at all. The viewer binds 127.0.0.1 by default — same as every other deployment in this README — and inside a container that's unreachable through docker run -p, because -p forwards to the container's network interface, not its loopback. Without this env var, docker logs will show the viewer listening, but the mapped host port will refuse every connection.
• Setting it to 0.0.0.0 means 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