Margin MCP Server
Margin exposes your documents, annotations, corrections, writing rules, and voice signals through a Model Context Protocol server. 20+ tools, 4 resources, and 3 prompts — available to any MCP-compatible AI client.
Quick Setup
Claude Desktop
{
"mcpServers": {
"margin": {
"command": "/Applications/Margin.app/Contents/Resources/mcp-server",
"args": ["--stdio"]
}
}
}Claude Code
{
"mcpServers": {
"margin": {
"command": "/Applications/Margin.app/Contents/Resources/mcp-server",
"args": ["--stdio"]
}
}
}Add to ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop, or .claude/settings.json / ~/.claude/settings.json for Claude Code.
When connected, Margin's title bar shows an MCP badge.
Documents
| Tool | Description | Key Parameters |
|---|---|---|
| margin_list_documents | List recent documents ordered by last opened | limit (default 20, max 100) |
| margin_get_document | Get full metadata for a single document | document_id (required) |
| margin_read_document | Read the file content of a document | document_id (required) |
| margin_search_documents | Full-text search with BM25 ranking and frecency boosting | query (required), limit (default 20, max 50) |
Annotations
| Tool | Description | Key Parameters |
|---|---|---|
| margin_get_annotations | Get all highlights and margin notes for a document, grouped by highlight | document_id (required) |
| margin_create_highlight | Create a new text highlight at specific positions | document_id, color (yellow/green/blue/pink/purple/orange), text_content, from_pos, to_pos (all required) |
| margin_highlight_by_text | Highlight by exact text match — no position math needed | document_id, text_to_highlight, color (required); note (optional) |
| margin_update_highlight_color | Change the color of an existing highlight | highlight_id, color (required) |
| margin_create_margin_note | Attach a note to an existing highlight | highlight_id, content (required) |
| margin_update_margin_note | Update the content of an existing margin note | note_id, content (required) |
| margin_delete_highlight | Delete a highlight and its attached notes (cascading) | highlight_id (required) |
| margin_delete_margin_note | Delete a single margin note without deleting its parent highlight | note_id (required) |
Corrections
| Tool | Description | Key Parameters |
|---|---|---|
| margin_get_corrections | Get writing corrections with context | document_id (optional filter), limit (default 200, max 2000) |
| margin_get_corrections_summary | Aggregate statistics: total count, by writing type, by document | (none) |
| margin_create_correction | Find text, create highlight, and record correction with notes | document_id, original_text, notes[] (required); writing_type, color (optional) |
| margin_delete_correction | Delete a correction and its associated highlight | highlight_id (required) |
| margin_update_correction_writing_type | Update the writing type of a correction | highlight_id, writing_type (required) |
| margin_set_correction_polarity | Set voice signal polarity: positive (emulate) or corrective (avoid) | highlight_id, polarity (positive/corrective) (required) |
| margin_get_voice_signals | Get corrections tagged with voice signal polarity | polarity (optional: positive/corrective), limit (default 500, max 2000) |
Writing Rules
| Tool | Description | Key Parameters |
|---|---|---|
| margin_get_writing_rules | Get writing rules from the database | writing_type (optional filter) |
| margin_get_writing_rules_markdown | Get rules formatted as markdown, grouped by type — suitable for prompts | writing_type (optional filter) |
| margin_update_writing_rule | Update fields of an existing rule | id (required); rule_text, severity, writing_type, example_before, example_after, notes, why, when_to_apply (optional) |
| margin_delete_writing_rule | Delete a writing rule by ID | id (required) |
Export
| Tool | Description | Key Parameters |
|---|---|---|
| margin_wait_for_export | Block until user exports annotations from Margin. Returns formatted markdown. | timeout_seconds (default 300, max 600) |
This tool uses long-polling. Call it, then ask the user to press ⌘⇧E in Margin. The tool returns when the export arrives or the timeout elapses.
Resources
| URI | Description |
|---|---|
| margin://documents | List of 20 most recent documents |
| margin://writing-rules | Writing rules formatted as markdown |
| margin://corrections/summary | Aggregate statistics about writing corrections |
| margin://latest-export | Most recent annotation export, updated in real-time via notifications |
Prompts
Three built-in prompts that structure common workflows.
| Prompt | Description | Arguments |
|---|---|---|
| review-writing | Review a document against writing rules | document_id (required) |
| analyze-corrections | Analyze correction patterns across documents | writing_type (optional) |
| export-and-review | Wait for export, then analyze annotations | timeout_seconds (optional) |
Writing Guard Hook
When writing rules are exported, Margin auto-generates a Claude Code hook at ~/.claude/hooks/margin-writing-guard.sh. The hook runs on every Edit and Write tool call, checking for kill words defined in your rules. If a banned word appears, the hook blocks the edit with an explanation.
# Auto-generated by Margin — do not edit manually
# Regenerated on every rules export
KILL_WORDS=("leverage" "utilize" "furthermore" "moreover" "additionally")
for word in "${KILL_WORDS[@]}"; do
if grep -qi "$word" "$1"; then
echo "BLOCKED: '$word' violates your writing rules"
exit 1
fi
doneThe hook is regenerated each time you export rules from Margin. To customize kill words, add corrections in Margin — the hook updates automatically.
Built by Sam Zoloth.