margo-mcp

MCP server for the Margo VS Code extension.

Exposes Margo notes stored in .notes.json (team vault) and .margo/local.notes.json (local vault) as tools any MCP-compatible AI tool can call — Claude Code, Cursor, Continue, Copilot (via MCP), and others.

No VS Code dependency. Works in the terminal, in any editor, on a server.

Use it (zero install — recommended)

Run via npx — no global install required. Configure your MCP client to spawn:

npx -y @aikaisi/margo-mcp

Claude Code

Add to ~/.claude/mcp.json (or run claude mcp add margo -- npx -y @aikaisi/margo-mcp):

{
  "mcpServers": {
    "margo": {
      "command": "npx",
      "args": ["-y", "@aikaisi/margo-mcp"]
    }
  }
}

Cursor

In ~/.cursor/mcp.json (or project-level .cursor/mcp.json):

{
  "mcpServers": {
    "margo": {
      "command": "npx",
      "args": ["-y", "@aikaisi/margo-mcp"]
    }
  }
}

Continue / other MCP clients

Same shape — consult each tool's MCP configuration docs for the exact config file location.

Optional: global install

If you prefer not to re-fetch on every start:

npm install -g @aikaisi/margo-mcp

Then use "command": "margo-mcp" (no npx) in your MCP client config.

How it finds your notes

When an AI tool spawns the server, it walks up from the current working directory looking for .notes.json or .margo/. If neither exists, it falls back to the nearest .git root so the first add_note call creates the vault there.

Tools

Read

| Tool | Description | |------|-------------| | list_notes | List notes with optional filters (category, priority, status, vault, file, text_search, limit). | | get_note | Fetch a single note by id. | | get_note_with_code | Fetch a note plus surrounding source lines — prefer this when the AI needs to reason about anchored code. | | get_notes_for_file | All notes on a given workspace-relative path. | | get_stats | Counts by category, priority, status, vault. |

Write

| Tool | Description | |------|-------------| | add_note | Create a note (file, line, title, text, optional category/priority/vault/author). | | update_note | Edit title, text, category, and/or priority. | | resolve_note / reopen_note | Toggle status. | | delete_note | Permanently remove. | | move_to_team / move_to_local | Move between vaults. |

Example AI prompts

• "Review the auth module and add BUG notes for anything that looks wrong."
• "List all high-priority open notes and summarize them."
• "Resolve note 1766658158896-klqlob5cs — I just fixed it."
• "Show me the code around note ... and explain what it's flagging."

Development

npm install
npm run build
npm start

License

AGPL-3.0-only. Commercial licensing available; contact [email protected].