Skip to main content
Glama
alaeddineG

md-annotate

by alaeddineG
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

md-annotate

A shared markdown review surface between Claude (via MCP) and humans (via browser). Push markdown documents, annotate them inline like a GitHub PR review, and generate structured revision prompts — all in a local-first workflow.

How it works

┌────────────────┐                ┌────────────────┐                ┌────────────────┐
│     Claude     │   MCP tools    │  md-annotate   │  Browser UI    │     Human      │
│   (or any AI)  │ ══════════════>│     daemon     │<══════════════ │   (reviewer)   │
│                │ <══════════════│                │ ══════════════>│                │
└────────────────┘  push / read   └────────────────┘ annotate/view  └────────────────┘

  1. Claude pushes a markdown document via the md_push MCP tool

  2. Human reviews in the browser — select text, add inline annotations (like PR review comments)

  3. Claude reads annotations via md_get_annotations and revises the document

  4. Repeat until done

Related MCP server: Batch Review

Quick start

# Clone and install
git clone https://github.com/alaeddineG/md-annotate.git
cd md-annotate
npm install

# Build the UI
npm run build

# Start the daemon
npm start
# → http://localhost:4242

Or use the setup script which handles everything including the MCP bridge:

# macOS / Linux
chmod +x setup.sh
./setup.sh

# Windows (PowerShell)
.\setup.ps1

MCP integration

md-annotate exposes four tools to Claude via the Model Context Protocol:

Tool

Description

md_push

Push a markdown document for review

md_get_annotations

Read all human annotations on a document

md_list_documents

List all documents in the review queue

md_clear_annotations

Clear annotations after incorporating feedback

Claude Desktop (stdio transport)

Add to your Claude Desktop MCP config:

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

Standalone MCP bridge

For environments where the MCP bridge needs to live outside the project directory (e.g. macOS sandbox restrictions with Claude Desktop):

# Build the self-contained bridge
npm run build:mcp

# Copy it somewhere accessible
mkdir -p ~/.mcp_servers/md-annotate
cp mcp-bridge.js ~/.mcp_servers/md-annotate/

Then configure Claude Desktop:

{
  "mcpServers": {
    "md-annotate": {
      "command": "node",
      "args": [
        "/Users/you/.mcp_servers/md-annotate/mcp-bridge.js",
        "--daemon-url", "http://localhost:4242"
      ]
    }
  }
}

Remote daemon

If the daemon runs on a different machine:

{
  "mcpServers": {
    "md-annotate": {
      "command": "npx",
      "args": ["md-annotate", "mcp", "--daemon-url", "http://192.168.1.100:4242"]
    }
  }
}

CLI

md-annotate start [--port 4242] [--host 0.0.0.0]   Start the daemon
md-annotate stop                                     Stop the daemon
md-annotate status                                   Show daemon status
md-annotate open                                     Open UI in browser
md-annotate push <file.md> [--id ID] [--context ""]  Push a file for review
md-annotate mcp [--daemon-url <url>]                 Run MCP stdio bridge

Architecture

md-annotate/
├── bin/cli.js            # CLI entry point
├── server/
│   ├── daemon.js         # Express server (REST API + SSE + static files)
│   ├── mcp.js            # MCP server (stdio + HTTP transports)
│   └── store.js          # File-based document/annotation storage
├── src/                  # React frontend (Vite + @primer/react)
│   ├── App.jsx           # Main app with SSE real-time updates
│   └── components/
│       ├── RawView.jsx          # Raw markdown with inline review threads
│       ├── MarkdownPreview.jsx  # Rendered markdown preview
│       ├── SelectionPopover.jsx # Text selection → annotation popover
│       ├── DocumentList.jsx     # Sidebar document list
│       ├── ModeToggle.jsx       # Raw/Preview toggle
│       └── PromptGenerator.jsx  # Generate revision prompt from annotations
├── mcp-standalone.js     # Entry point for standalone MCP bridge
├── setup.sh              # Setup script (macOS/Linux)
└── setup.ps1             # Setup script (Windows)

Storage: Documents and annotations are persisted as JSON files under ~/.md-annotate/documents/.

Real-time: The browser connects via Server-Sent Events (SSE) so annotations and document updates appear instantly — whether created from the UI or pushed via MCP.

Development

# Start Vite dev server (hot reload) + proxy to daemon
npm run dev

# In another terminal, start the daemon
node server/daemon.js

Platform support

Works on macOS, Linux, and Windows. The daemon, CLI, and MCP bridge are pure Node.js with no native dependencies. The setup.sh script is bash-only (macOS/Linux) — on Windows, run the steps manually or use WSL.

Requirements

  • Node.js >= 18

  • A browser

  • Claude Desktop or any MCP-compatible client (for the AI side)

License

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/alaeddineG/md-annotate'

If you have feedback or need assistance with the MCP directory API, please join our Discord server