mdshare

# mdshare

> Share markdown as a link anyone can comment on and edit, with no account. Free. Upload markdown, get a shareable link, collaborate in real time; works from the browser and from AI tools via MCP.

mdshare turns any markdown into a shareable link. The primary interface is the MCP server (`npx mdshare-mcp`; the same package is also a command line), which works with Claude, ChatGPT/Codex, Gemini CLI, Cursor, and Windsurf. MCP tools: `upload_markdown`, `read_document`, `update_document`, `patch_document`, `generate_link`, `list_links`, `revoke_link`, `list_comments`, `post_comment`, `resolve_comment`, `get_versions`, `list_my_documents`, `get_admin_url`, `register_document`. The bundled `mdshare-tools` skill auto-invokes on prompts like "share this markdown", "publish my notes", or "give me a link for this doc".

## MCP server

- Hosted, read only: `https://mdshare.live/mcp` (Streamable HTTP, no install). Pass a share link to `read_document`, `list_comments` or `get_versions`. It refuses admin links and stores or logs no keys; to upload or edit, use the npm package.
- [mdshare-mcp on npm](https://www.npmjs.com/package/mdshare-mcp): install and run with `npx mdshare-mcp` (registry id `io.github.sathya-sankaran/mdshare`)
- [MCP setup guide](https://mdshare.live/share-markdown-with-ai): connect Claude, ChatGPT, Gemini CLI, Cursor, or Windsurf

## Command line

The same npm package is a command line when given a subcommand (with no arguments it runs the MCP server). It shares admin keys with the MCP server, stores them locally and never prints them.

- `npx mdshare-mcp upload notes.md`: print a share link (comment permission by default; `--permission view|comment|edit`, `--title`, `--expires 7d`); `-` reads from stdin
- `npx mdshare-mcp update <doc-id> notes.md`: replace the content; refuses if someone edited it since your last upload, update or read (`--base-hash`, `--force`)
- `npx mdshare-mcp read <doc-id|link> [-o out.md]`, `ls` (your stored documents)
- `npx mdshare-mcp link <doc-id> --view|--comment|--edit [--expires 30d]`, `links <doc-id>`, `revoke <doc-id> <link-token>`, `expire <doc-id> <30d|12h>`
- `npx mdshare-mcp --help`: every command

## Plugins

- [Claude Code plugin setup](https://mdshare.live/install-mdshare-plugin): `/plugin marketplace add urbanmorph/mdshare && /plugin install mdshare@urbanmorph`
- [Claude Code plugin source](https://github.com/urbanmorph/mdshare/tree/main/plugins/claude-code)
- [Cursor plugin listing](https://cursor.directory/plugins/mdshare): click "Add to Cursor", or paste `{"mcpServers":{"mdshare":{"command":"npx","args":["-y","mdshare-mcp"]}}}` into `~/.cursor/mcp.json`
- [Cursor plugin source](https://github.com/urbanmorph/mdshare/tree/main/plugins/mdshare-cursor)
- [Obsidian plugin listing](https://community.obsidian.md/plugins/mdshare): right-click any `.md` file → "Share on mdshare"
- [Obsidian plugin source](https://github.com/urbanmorph/obsidian-mdshare)

## API

- [REST API reference](https://mdshare.live/docs/raw): full endpoint docs, base URL `https://mdshare.live`
- [MCP setup](https://mdshare.live/share-markdown-with-ai): use mdshare from an AI client
- [About mdshare](https://mdshare.live/about): what mdshare is and who it is for

Quick reference:

- Upload: `POST /api/documents` (Content-Type: text/markdown, body: raw markdown)
- Read: `GET /api/d/{id}?key={key}` (Accept: text/markdown for raw)
- Update: `PUT /api/d/{id}?key={edit_key}` (Content-Type: text/markdown, X-Author: name, optional X-Base-Hash: content_hash your edit is based on; returns 409 with the latest content if the document changed)
- Patch: `PATCH /api/d/{id}?key={edit_key}` (JSON `{operations:[{find,replace,replace_all?}], author?}`) — preferred for small edits to large docs
- Links: `POST /api/d/{id}/links?key={admin_key}` (`{permission, label, expires_at}`)
- Comments: `POST /api/d/{id}/comments?key={key}` (`{content, author_name, anchor_text, parent_id}`) — replies nest one level
- Versions: `GET /api/d/{id}/versions?key={key}`
- Presence: `POST /api/d/{id}/presence?key={key}` (`{session_id, name}`)
- Permissions: `adm_` full control · `edt_` read+write · `cmt_` read+comment · `viw_` read only
- Limits: 90-day expiry · 10 creates/min, 50/day per IP · 30 updates/min · 20 comments/min · max 50 links/doc · max 10MB · 429 includes Retry-After · expired docs return 410 Gone

## Convert then share

mdshare is the sharing layer; conversion happens upstream. Pattern: `<converter> file | curl -X POST -H "Content-Type: text/markdown" --data-binary @- https://mdshare.live/api/documents`

- [markitdown](https://github.com/microsoft/markitdown): PDF/DOCX/PPTX/XLSX/HTML/audio to markdown (Microsoft)
- [pandoc](https://pandoc.org): LaTeX/EPUB/RST/org/Jupyter to markdown
- [Docling](https://github.com/docling-project/docling): RAG-focused PDF/DOCX/PPTX/HTML conversion with table recovery (IBM)
- [Marker](https://github.com/VikParuchuri/marker): fast, accurate PDF to markdown for LLM ingestion
- [Firecrawl](https://www.firecrawl.dev): scrape any URL to clean markdown
- [Jina Reader](https://jina.ai/reader): free URL to markdown via `r.jina.ai/{url}`
- [Convert + share workflow guide](https://mdshare.live/convert-and-share-markdown): end-to-end conversion-then-share recipes

## Optional

- [Homepage](https://mdshare.live): upload from the browser
- [GitHub: urbanmorph/mdshare](https://github.com/urbanmorph/mdshare): source and issues
- [Privacy](https://mdshare.live/privacy): data handling and document expiry