mdsync Docs

Installation

Use npx when you want a one-off run. Install globally when you use it often.

npx markdownsync README.md

npm install -g markdownsync
mdsync README.md

CLI reference

Command	What it does
`mdsync <file-or-directory>`	Start live mode. Files open as a single document. Directories open as a docs workspace.
`mdsync view <file-or-directory>`	Explicit form of live mode.
`mdsync serve <directory>`	Force directory mode.
`mdsync build <directory> --out <directory>`	Generate a static HTML site from a markdown folder.
`mdsync mcp`	Start the MCP server over stdio.
`mdsync --help`	Print usage.

Live mode flags

Flag	What it does
`--port`, `-p`	Choose the HTTP port. Default is `3456`.
`--light`	Start the viewer in light mode.
`--no-edit`	Disable browser editing and keep the session read-only.
`--no-open`	Start the server without opening a browser tab.

Build flags

Flag	What it does
`--out <dir>`	Output directory for the generated site.
`--title "My Docs"`	Override the generated site title.
`--base /docs`	Set the base path for static hosting under a subdirectory.
`--theme dark\|light\|auto`	Choose the default theme for the built site.

Single file mode

Point mdsync at a markdown file and it opens a rendered document in the browser. Edits sync both ways: change the file on disk and the browser updates, or edit in the browser and the markdown file is rewritten.

mdsync README.md
mdsync ./notes/today.md --port 8080
mdsync ./draft.md --light --no-open

Browser editing is enabled by default. Use --no-edit when you want a read-only session for review, presentations, or demos.

Directory mode

Point mdsync at a directory to turn a folder of markdown files into a browsable workspace. It indexes the folder, opens the first markdown file it finds, and watches for changes across the workspace.

mdsync ./docs
mdsync serve ./docs
mdsync ./knowledge-base --no-edit

Directory mode is the fastest way to review or clean up a docs tree, notes folder, or AI-generated batch of markdown files.

Static build

Use the same markdown folder to generate a deployable static site. The output is self-contained HTML, so you can ship it to any static host without a framework or theme system.

mdsync build ./docs --out ./site
mdsync build ./docs --out ./public --title "Team Docs"
mdsync build ./docs --out ./dist --base /docs --theme dark

MCP integration

Run mdsync mcp to expose your markdown files through MCP tools. This is the agent loop: open a file, read it, inspect feedback, update it, write it back.

mdsync mcp
npx -y markdownsync mcp

Claude Desktop

On macOS, add this to ~/Library/Application Support/Claude/claude_desktop_config.json.

{
  "mcpServers": {
    "mdsync": {
      "command": "npx",
      "args": ["-y", "markdownsync", "mcp"]
    }
  }
}

Cursor

Add this to ~/.cursor/mcp.json or project-local .cursor/mcp.json.

{
  "mcpServers": {
    "mdsync": {
      "command": "npx",
      "args": ["-y", "markdownsync", "mcp"]
    }
  }
}

OpenClaw

If your OpenClaw install reads mcp.servers, add this block to that config.

{
  "mcp": {
    "servers": {
      "mdsync": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "markdownsync", "mcp"]
      }
    }
  }
}

Tool reference

Tool	Params	What it returns
`present`	`path: string`	Opens a markdown file or directory in the browser and returns the viewer URL, file path, and feedback path.
`get_document`	`path: string`	Returns the current markdown content for a file.
`get_feedback`	`path: string`	Returns the structured feedback JSON stored next to the markdown file.
`write_document`	`path: string`, `content: string`	Writes markdown back to disk and returns a confirmation object with the resolved path.

Tool paths are resolved relative to the directory where you start mdsync mcp. Start it from the repo or workspace you want the agent to work inside.

Examples and recipes

Review one README

mdsync README.md

Browse an entire docs folder without editing

mdsync ./docs --no-edit

Build and deploy a docs site under a subpath

mdsync build ./docs --out ./public --base /docs
netlify deploy --dir ./public --prod

Let an MCP client update markdown in your repo

cd /path/to/repo
mdsync mcp

After that, the client can call get_document, edit the content locally, and send the full replacement through write_document.

Command reference and MCP setup.