What is this?

simplemd-mcp is an MCP (Model Context Protocol) server that connects AI coding tools like Claude Code to the SimpleMD Chrome extension.

Generate a Mermaid diagram, a markdown report, or formatted notes in your terminal — and see them rendered in your browser instantly.

You: "Create a system architecture diagram for this project"

Claude: generates mermaid diagram → calls simplemd_push
        → diagram appears rendered in SimpleMD side panel

How it works

Claude Code          MCP Server         Native Host        SimpleMD Extension
    │                    │                   │                      │
    │── tool call ──────>│                   │                      │
    │  (stdio JSON-RPC)  │── request ───────>│                      │
    │                    │  (Unix socket)    │── native message ───>│
    │                    │                   │  (Chrome protocol)   │── save file
    │                    │                   │                      │── refresh UI
    │                    │                   │<── response ─────────│
    │                    │<── response ──────│                      │
    │<── result ─────────│                   │                      │

The bridge consists of two processes connected by a Unix domain socket:

• MCP Server — launched by Claude Code, speaks JSON-RPC over stdio
• Native Messaging Host — launched by Chrome, relays messages between the socket and the extension

Quick start

Prerequisites

• SimpleMD Chrome extension installed
• Node.js 18+
• Claude Code or any MCP-compatible client

1. Install

npm install -g simplemd-mcp

2. Register the native messaging host

simplemd-mcp-install

This registers the bridge with Chrome so the extension can communicate with it. It will print the MCP configuration to add to your project.

3. Configure your MCP client

Add to your project's .mcp.json:

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

Or for Claude Code's global config (~/.claude/claude_code_config.json):

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

4. Use it

Open SimpleMD in Chrome (side panel or full window), then in Claude Code:

"Push a hello world markdown file to SimpleMD"

"Create a mermaid flowchart of the auth flow and preview it in SimpleMD"

"List my files in SimpleMD"

MCP Tools

simplemd_push

Create a new markdown file in the extension.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content | string | yes | Markdown content | | name | string | no | File name (defaults to timestamp) | | folder | string | no | Folder name (created if it doesn't exist) | | profile | string | no | Target Chrome profile email (required with multiple profiles + PRO) |

simplemd_preview

Create a file and immediately open it in preview mode — ideal for diagrams and formatted content.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | content | string | yes | Markdown content | | name | string | no | File name (defaults to timestamp) | | profile | string | no | Target Chrome profile email |

simplemd_list_files

List all files stored in the extension with their IDs, names, folders, and dates.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | profile | string | no | Target Chrome profile email |

simplemd_update_file

Update the content of an existing file by its ID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | yes | File ID (use simplemd_list_files to find it) | | content | string | yes | New markdown content | | profile | string | no | Target Chrome profile email |

simplemd_list_profiles

List all connected Chrome profiles. Shows email, name, PRO status, and connection time. Use this to discover available profiles before targeting a specific one.

No parameters.

simplemd_status

Check the connection status and diagnose issues. Pings each connected profile and reports PRO/multi-profile status.

No parameters.

Multi-profile support

SimpleMD MCP supports multiple Chrome profiles simultaneously. Each profile registers with the MCP server when Chrome starts, identified by the user's email address.

How it works:

• Each Chrome profile runs its own instance of the SimpleMD extension
• The native messaging host registers each profile with the MCP server
• Use simplemd_list_profiles to see which profiles are connected
• Use the profile parameter (email) to target a specific profile

Free vs PRO:

| Scenario | Free | PRO | |----------|------|-----| | Single profile | Works normally | Works normally | | Multiple profiles, no profile param | Auto-routes to first connected | Requires profile param | | Multiple profiles, with profile param | Upgrade required | Routes to specified profile |

Multi-profile targeting is unlocked when any connected profile has a SimpleMD PRO license. Upgrade to PRO to unlock full multi-profile routing.

Example workflows

Visualize a codebase architecture:

You: "Analyze the project structure and create a mermaid diagram showing
      the module dependencies, then preview it in SimpleMD"

Generate meeting notes:

You: "Summarize the changes in the last 5 commits as formatted markdown
      and push it to SimpleMD as 'Sprint Review Notes'"

Iterative diagram editing:

You: "List my SimpleMD files"
You: "Update the architecture diagram with the new auth module"

Organize by project:

You: "Push this API documentation to SimpleMD in the 'backend-docs' folder"

Update

To update to the latest version:

npm update -g simplemd-mcp && simplemd-mcp-install

Restart Claude Code after updating to pick up the new MCP server.

Uninstall

Remove the native messaging host registration:

simplemd-mcp-install uninstall

Remove the package:

npm uninstall -g simplemd-mcp

Platform support

| Platform | Status | |----------|--------| | macOS | Supported | | Linux | Supported | | Windows | Not yet supported |

Troubleshooting

"SimpleMD extension is not connected"

• Make sure the SimpleMD extension is open in Chrome (side panel or full window tab)
• Check the extension's service worker console (chrome://extensions → SimpleMD → "Service Worker") for connection errors

"Specified native messaging host not found" in extension console

• Run simplemd-mcp-install again to re-register the native host
• Make sure Node.js is in your PATH
• Restart Chrome after installing

Tools not appearing in Claude Code

• Verify .mcp.json is in your project root or config is in ~/.claude/claude_code_config.json
• Restart Claude Code after adding the MCP config

Development

git clone https://github.com/cafali-com/simplemd-mcp.git
cd simplemd-mcp
npm install
npm run build

Run in watch mode:

npm run dev

License

MIT - Cafali Inc