# md2link MCP Guide

> 📂 Folder: [Guide](https://md2link.com/f/gdp57v3zm8mn)

Use **md2link** from AI agents (Claude Desktop, Cursor, VS Code, Claude Code) to create, manage, and share markdown documents — all without leaving your editor.

---

## What is md2link?

[md2link.com](https://md2link.com) is a fast markdown editor and publishing platform. Write markdown → get a shareable link instantly.

The **MCP server** (`md2link-mcp`) lets AI agents interact with md2link programmatically via the [Model Context Protocol](https://modelcontextprotocol.io/).

---

## Quick Start

### 1. Get an API Key

Go to [md2link.com/settings/account/api-keys](https://md2link.com/settings/account/api-keys) and create a key (starts with `cm_live_...`).

### 2. Configure Your Client

Add the MCP server to your client config:

```json
{
  "mcpServers": {
    "md2link": {
      "command": "npx",
      "args": ["-y", "md2link-mcp"],
      "env": {
        "MD2LINK_API_KEY": "cm_live_YOUR_KEY_HERE"
      }
    }
  }
}
```

**Config file locations:**

| Client | Path |
|--------|------|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `.claude/settings.json` or `~/.claude/settings.json` |
| Cursor | `.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` |

### 3. Restart Your Client

After saving config, restart the client. The 11 md2link tools will appear in the tool picker.

---

## Available Tools

| Tool | Description |
|------|-------------|
| `whoami` | Verify API key — returns user profile + active key count |
| `create_doc` | Create a new markdown document |
| `list_docs` | List your documents (with pagination + filters) |
| `get_doc` | Read a document's full markdown content |
| `update_doc` | Partially update a document |
| `delete_doc` | Permanently delete a document |
| `create_folder` | Create a folder to organize docs |
| `list_folders` | List your folders |
| `get_folder` | Read a folder and its child documents |
| `update_folder` | Update folder properties |
| `delete_folder` | Delete a folder (docs inside are orphaned, not deleted) |

---

## Document Options

When creating or updating docs, you can set:

| Option | Values | Default |
|--------|--------|---------|
| `visibility` | `public`, `unlisted`, `password` | `unlisted` |
| `password` | 4-100 chars (required if visibility = password) | — |
| `expiresAt` | ISO 8601 datetime | never |
| `folderId` | UUID of target folder | none |
| `status` | `draft`, `reviewing`, `final` | — |

---

## Workflows & Examples

### Publish a Note Instantly

> "Create a public doc with my meeting notes"

The agent calls `create_doc` with your markdown content and returns a shareable `https://md2link.com/d/xxxxx` link.

### Organize Docs in Folders

> "Create a folder called 'Project Alpha' and move my last 3 docs into it"

The agent calls `create_folder`, then `update_doc` on each doc to set `folderId`.

### Draft → Review → Final Pipeline

> "Set my doc to reviewing status"

Use `update_doc` with `status: "reviewing"` to track document lifecycle.

### Password-Protected Sharing

> "Create a password-protected doc with password 'team2024'"

The agent creates a doc with `visibility: "password"` — recipients need the password to view.

### Auto-Expiring Links

> "Share this but expire it in 7 days"

Pass `expiresAt` as an ISO 8601 date. The doc becomes inaccessible after that time.

---

## Use Cases

- **Meeting notes** — Write notes in your editor, push to md2link for team sharing
- **Documentation** — Publish internal guides as shareable links
- **Content drafts** — Draft blog posts or newsletters, share review links
- **Code snippets** — Share formatted code with syntax highlighting
- **Reports** — Generate reports from data and publish instantly
- **Temporary sharing** — Auto-expiring links for sensitive content

---

## Security

- API key is sent only via `x-api-key` HTTP header (never in URLs or logs)
- All requests use HTTPS/TLS
- The MCP server has no filesystem access — it only talks to the md2link REST API
- Rate limit: 1000 requests/hour per user

---

## Tips

- Use `whoami` to verify your setup is working
- `list_docs` supports filters: `folderId`, `visibility`, `status`
- Pagination: pass the `cursor` from a previous response to get the next page
- Max document size: 500,000 characters
- Folder names: max 60 characters
- Titles: max 200 characters

---

## Links

- Website: [md2link.com](https://md2link.com)
- npm: [md2link-mcp](https://www.npmjs.com/package/md2link-mcp)
- API docs: [md2link.com/docs/api](https://md2link.com/docs/api)
- OpenAPI spec: [md2link.com/api/v1/openapi.json](https://md2link.com/api/v1/openapi.json)
- API keys: [md2link.com/settings/account/api-keys](https://md2link.com/settings/account/api-keys)