mdshare API

Base URL: https://mdshare.live

Zero-login markdown sharing. Upload, get links, collaborate. No accounts needed.

Raw markdown: curl https://mdshare.live/docs/raw

Quick Start

Upload a document

curl -X POST https://mdshare.live/api/documents \
  -H "Content-Type: text/markdown" \
  --data-binary @your-file.md

Response:

{
  "document_id": "abc123",
  "admin_key": "adm_xK9mQ4r8...",
  "admin_url": "https://mdshare.live/d/abc123?key=adm_xK9mQ4r8..."
}

Save the admin_key — it's your master key. If lost, admin access is lost.

Read a document

# JSON (default)
curl "https://mdshare.live/api/d/{id}?key={any_valid_key}"

# Raw markdown
curl -H "Accept: text/markdown" "https://mdshare.live/api/d/{id}?key={key}"

Update a document

curl -X PUT "https://mdshare.live/api/d/{id}?key={edit_or_admin_key}" \
  -H "Content-Type: text/markdown" \
  --data-binary @updated.md

Patch a document (find/replace)

curl -X PATCH "https://mdshare.live/api/d/{id}?key={edit_or_admin_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "find": "old text", "replace": "new text" }
    ],
    "author": "Your Name"
  }'

Response:

{
  "applied": 1,
  "operations": [{ "index": 0, "status": "ok" }],
  "content_hash": "abc123..."
}

Each find must be unique in the document. Set replace_all: true to replace all occurrences. Statuses: ok, not_found, ambiguous, invalid.

Generate a share link (admin only)

curl -X POST "https://mdshare.live/api/d/{id}/links?key={admin_key}" \
  -H "Content-Type: application/json" \
  -d '{"permission": "edit", "label": "for-team"}'

Key Types

Endpoints

Documents

Links (admin only)

Comments

Versions (edit history)

The GET /api/d/:id response also includes last_edited_by, last_edited_via, and last_edited_at.

Presence

Rate Limits

Errors

Notes

• Content is sanitized server-side (no raw HTML, XSS protection)
• Binary files are rejected (magic byte detection)
• Links only allow http:, https:, mailto: protocols
• All content should be treated as user-generated
• API responses include X-Content-Source: user-generated header
• Write endpoints (POST/PUT/PATCH) return Server-Timing headers and a processing_ms field for latency tracking

Use with AI

See /share-markdown-with-ai for a dedicated guide with per-client setup, tool reference, and FAQs.

MCP Setup

mdshare works as an MCP server with Claude, ChatGPT/Codex, and Gemini CLI.

npx mdshare-mcp

Claude Desktop / Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mdshare": {
      "command": "npx",
      "args": ["mdshare-mcp"]
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "mdshare": {
      "command": "npx",
      "args": ["mdshare-mcp"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "mdshare": {
      "command": "npx",
      "args": ["mdshare-mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mdshare": {
      "command": "npx",
      "args": ["mdshare-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mdshare": {
      "command": "npx",
      "args": ["mdshare-mcp"]
    }
  }
}

What to tell your AI

• “Upload my-notes.md to mdshare and give me an edit link”
• “Read this mdshare document and summarize the comments”
• “Incorporate the feedback and resolve the comments”
• “Share this markdown with view-only access”
• “Who edited this document last?”
• “Post a comment on the budget section”
• “List all links for this document”
• “Revoke the edit link I shared with the team”
• “Save this mdshare document to /tmp/notes.md”

Tip: When uploading a file already on disk, the MCP server reads it directly via file_path instead of echoing the bytes through the conversation. This is dramatically faster for AI workflows. Same for downloads via output_path.

Without MCP (works with any AI)

No setup needed. Just tell your AI chatbot:

Read https://mdshare.live/docs/raw to learn the mdshare API,
then upload this markdown and give me a share link.

Works with Claude, ChatGPT, Gemini, Copilot, or any AI that can make HTTP calls.

VS Code Extension

Share markdown files directly from VS Code. Right-click any .md file or select text and share it instantly. Also works in Cursor and Windsurf since they support the VS Code extension format.

Install

1. Open the Extensions panel in VS Code (Cmd+Shift+X or Ctrl+Shift+X)
2. Search for mdshare and click Install, or install directly from the Marketplace page

Or install manually: download mdshare-vscode.vsix, then Cmd+Shift+P → Install from VSIX.

Usage

• Share a file: Right-click a .md file in the Explorer → “Share on mdshare”
• Share a selection: Select text in any editor → right-click → “Share Selection on mdshare”

The admin URL is automatically copied to your clipboard.

Obsidian Plugin

Share markdown files directly from Obsidian. Right-click any file, select text, or use the command palette. Listed in the official Obsidian Community Plugins directory.

Install via Community Plugins (recommended)

1. Open Obsidian → Settings → Community Plugins
2. If you haven’t already, turn off Restricted Mode
3. Click Browse and search for mdshare
4. Click Install, then Enable

Alternative: BRAT (for beta builds)

1. Install BRAT from Community Plugins
2. In BRAT settings, click “Add Beta Plugin”
3. Enter: urbanmorph/obsidian-mdshare

Use BRAT only if you want to test pre-release builds before they ship to the directory.

Alternative: manual install

1. Download main.js and manifest.json
2. Create a folder: <your-vault>/.obsidian/plugins/mdshare/
3. Copy both files into that folder
4. Enable in Settings → Community Plugins

Usage

• Share a file: Right-click a file in the explorer → “Share on mdshare”
• Share a selection: Select text → right-click → “Share selection on mdshare”
• Command palette: Cmd/Ctrl+P → “mdshare: Share current file”

The admin URL is automatically copied to your clipboard.