MCP Server

MarkDocs exposes 23 tools and 2 resources over stdio . Your MCP client (Claude Code, Claude Desktop, Cursor, etc.) spawns markdocs mcp as a child process automatically — you never run it yourself.

Setup

1. Install the CLI


curl -fsSL https://markdocs.sh/install.sh | bash

2. Authenticate


markdocs login --url https://your-instance.com --handle yourhandle
markdocs setup

Or pass credentials via environment variables in the client config (see below).

3. Add to your MCP client

Add the config to your client’s config file. The client will start and manage the markdocs mcp process for you.

Claude Code (.mcp.json in your project root):


{
  "mcpServers": {
    "markdocs": {
      "command": "markdocs",
      "args": ["mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):


{
  "mcpServers": {
    "markdocs": {
      "command": "markdocs",
      "args": ["mcp"]
    }
  }
}

Cursor / VS Code — same pattern. Any stdio-compatible MCP client works.

With env vars (skip markdocs login):


{
  "mcpServers": {
    "markdocs": {
      "command": "markdocs",
      "args": ["mcp"],
      "env": {
        "MARKDOCS_API_KEY": "your-api-key",
        "MARKDOCS_URL": "https://your-instance.com"
      }
    }
  }
}

Tools

Documents

Tool	Description
`list_documents`	List all documents
`create_document`	Create a document
`get_document`	Get document by ID
`delete_document`	Soft-delete a document
`get_document_content`	Get markdown content
`update_document_content`	Replace entire markdown content
`edit_document`	Text-based editing with find/replace, insert, delete, comment, and suggest operations

Comments

Tool	Description
`list_comments`	List comments (flat)
`list_comment_threads`	List comments as threaded conversations with nested replies
`add_comment`	Add inline comment (position-based)
`reply_to_comment`	Reply to a comment thread, optionally resolving it
`resolve_comment`	Resolve a comment
`unresolve_comment`	Unresolve a previously resolved comment
`delete_comment`	Delete a comment

Suggestions

Tool	Description
`list_suggestions`	List suggestions
`add_suggestion`	Propose a text replacement (position-based)
`accept_suggestion`	Accept a suggestion
`reject_suggestion`	Reject a suggestion

Other

Tool	Description
`get_history`	Get edit history
`list_users`	List workspace users
`list_collaborators`	List document collaborators
`share_document`	Share by handle
`unshare_document`	Remove collaborator

edit_document

The edit_document tool is the recommended way for agents to modify documents. It uses text-based targeting so agents find content by quoting visible text instead of counting character positions.

Operations


{
  "document_id": "doc-id",
  "operations": [
    { "op": "replace", "find": "old text", "replace": "new text" },
    { "op": "insert", "after": "some heading", "text": "\n\nNew paragraph." },
    { "op": "insert", "before": "## Section", "text": "Inserted before.\n\n" },
    { "op": "delete", "find": "text to remove" },
    { "op": "comment", "on": "text to comment on", "body": "Is this right?" },
    { "op": "suggest", "find": "old phrasing", "replace": "better phrasing" }
  ]
}

Content ops (replace, insert, delete) apply first as one batch. Review ops (comment, suggest) apply after against the updated content.

Use "occurrence" (0-indexed number, "first", or "last") to disambiguate when the same text appears multiple times.

Resources

URI	Description
`markdocs://documents`	All documents as JSON
`markdocs://documents/{id}`	Single document as JSON