burn-mcp-server

v2.1.1

Published

a day ago

Burn MCP — give your AI agent a reading workflow. 26 tools to search, triage, burn, vault, and analyze your saved articles. Works with Claude, Cursor, Windsurf.

Burn — Personal Knowledge Base MCP Server

Want this badge in your own README? Grab the markdown at burn451.cloud/developers#badges.

Your reading data as an AI-accessible knowledge base. 26 tools for Claude, Cursor, Windsurf, and any MCP-compatible agent.

Watch the real Claude → Burn walkthrough — the exact read-only prompt, tool calls, sources, and limits are published so you can reproduce it.

You need a free Burn account to use this server. Fastest path: open Burn on the web → Settings → MCP Server → Copy Access Token. Prefer the app? Download Burn for iPhone. Burn has a free tier (5 saves/day, all 26 MCP tools included) and a Pro plan at $4.99/month for unlimited saves.

How it works

Burn is a read-later app with a 24-hour deadline — saves auto-burn unless you read or rescue them. The honest answer to the bookmark graveyard problem — research suggests 84% of saved bookmarks are never revisited (Bergman, Whittaker & Schooler, 2021).

Triage flow:

Flame → New links. 24h to read or they burn.
Spark → You read it. Stays 30 days.
Vault → Permanent. Your curated knowledge.
Ash → Expired. They had their chance.

The MCP server lets your AI agent search, triage, organize, and analyze everything you've saved. Built for Claude users who want their reading history as context.

Migrating from another tool? Burn is a Pocket replacement (Mozilla shut Pocket down July 2025), an Omnivore alternative (acquired by ElevenLabs late 2024), and a Matter app alternative.

Quick Start

1. Get your token

Create a free Burn account — iOS app or web
Open the app → Settings → MCP Server → Generate token → Copy

The server exchanges your token for a short-lived Supabase session and caches it in ~/.burn/mcp-session.json. No re-login on each run.

2a. Remote — Streamable HTTP (fastest)

Use the hosted endpoint with the same Burn token. Nothing runs locally:

{
  "mcpServers": {
    "burn": {
      "type": "http",
      "url": "https://burn-mcp-server.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

For claude.ai, open Settings → Connectors → Add custom MCP, use the endpoint above, and add the same Authorization header.

2b. Local — stdio fallback

Run the npm package locally in Claude Desktop, Cursor, Windsurf, or Claude Code:

{
  "mcpServers": {
    "burn": {
      "command": "npx",
      "args": ["burn-mcp-server"],
      "env": {
        "BURN_MCP_TOKEN": "<your-token>"
      }
    }
  }
}

3. Start asking

"What did I save about system design?"
"Triage my Flame — what should I keep?"
"Create a collection from my AI bookmarks"

Add to Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "burn": {
      "command": "npx",
      "args": ["burn-mcp-server"],
      "env": { "BURN_MCP_TOKEN": "<your-token>" }
    }
  }
}

Add to Claude Code (CLI)

claude mcp add burn -e BURN_MCP_TOKEN=<your-token> -- npx burn-mcp-server

Example prompts

Reading triage:

"Go through my Flame inbox, read each article, keep anything about AI agents and burn the rest."
"What's about to expire in the next 6 hours that I'd regret losing?"

Knowledge retrieval:

"Search my Vault for everything on context engineering and summarize the main schools of thought."
"Which authors do I save most often? What does that say about my reading gaps?"

Research curation:

"Create a collection called 'MCP in production' from my saves, then write an overview of what my sources agree and disagree on."
"Add a watched source for Simon Willison's blog so new posts land in my Flame."

Writing with your own sources:

"I'm writing about read-later apps. Pull every relevant bookmark I have and list the claims I can support with a source."

Tools (26)

Search & Read

| Tool | What it does | |------|-------------| | search_vault | Search permanent bookmarks by keyword | | list_vault | List Vault bookmarks by category | | list_sparks | List recently read bookmarks (30-day window) | | search_sparks | Search Sparks by keyword | | list_flame | List inbox — what's about to burn | | get_flame_detail | Full detail on a Flame bookmark | | get_bookmark | Get any bookmark by ID | | get_article_content | Get full article content + analysis | | fetch_content | Fetch content from a URL (X, Reddit, YouTube, WeChat) | | list_categories | All Vault categories with counts | | get_collections | List all Collections | | get_collection_overview | Collection detail with AI overview |

Triage (Agent as your filter)

| Tool | What it does | |------|-------------| | move_flame_to_spark | Keep it — worth reading. Optional insight. | | move_flame_to_ash | Burn it. Optional reason. | | move_spark_to_vault | Promote to permanent. Optional category. | | move_spark_to_ash | Not valuable enough to keep. | | batch_triage_flame | Triage up to 20 at once. |

Collections (Agent as your curator)

| Tool | What it does | |------|-------------| | create_collection | Create a topic bundle with initial bookmarks | | add_to_collection | Add bookmarks (deduplicates) | | remove_from_collection | Remove bookmarks | | update_collection_overview | Write AI overview (theme, synthesis, gaps) |

Analysis (Agent as your analyst)

| Tool | What it does | |------|-------------| | write_bookmark_analysis | Write structured analysis back to a bookmark |

Auto-Feed (Agent as your scout)

| Tool | What it does | |------|-------------| | add_watched_source | Watch an X user, RSS feed, or YouTube channel. New posts flow into Flame automatically. | | list_watched_sources | List all active watched sources | | remove_watched_source | Stop watching a source | | scrape_watched_sources | Fetch new content from watched sources on demand |

What this doesn't do (yet)

Honest boundaries, so you know what to expect before connecting an agent:

No save/add-URL tool. The agent can search, read, triage, and organize what's already in your Flame/Spark/Vault — it can't add a new URL to your inbox itself. Save from the iOS app, the Chrome Web Clipper, or burn451.cloud first; the agent picks up from there.
Keyword search, not semantic/vector search. search_vault and search_sparks match on title, tags, and the AI-generated takeaway — not embedding similarity. Search by topic keyword, not by vague description.
No delete. Tools move bookmarks between Flame → Spark → Vault → Ash; nothing permanently deletes a row through MCP.
Remote and local transports, but no OAuth flow yet. The hosted endpoint uses Streamable HTTP at https://burn-mcp-server.vercel.app/api/mcp; local clients run npx burn-mcp-server over stdio. Both require a token you generate and paste once per client.
Read/triage is the mature path; agent-writes-back is newer. write_bookmark_analysis and update_collection_overview let the agent write structured notes back to your data. These write tools are newer and less battle-tested than the read/search/triage tools above.

Resources

| URI | Content | |-----|---------| | burn://vault/bookmarks | All Vault bookmarks (JSON) | | burn://vault/categories | Category list (JSON) |

Use Cases

Personal knowledge management — Your agent searches your reading history to answer questions, find patterns, and surface forgotten gems. See AI bookmark management concepts.

Research workflows — Create collections on topics you're exploring. Agent writes overviews synthesizing your sources. Examples: vault as Karpathy LLM wiki, Paul Graham vault, Simon Willison vault.

Reading triage — Agent reviews your Flame inbox, reads the content, decides what's worth keeping. Solves the reading list app problem of saves piling up.

Cross-tool intelligence — Use with Claude Code, Cursor, or Windsurf. Your bookmarks become context for coding, writing, and thinking. The MCP server architecture is open and documented.

Free vs paid choice — Burn's free tier includes all 26 MCP tools (5 saves/day); Pro is $4.99/month. See free bookmark manager comparison for honest landscape across 8 truly-free options.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | BURN_MCP_TOKEN | Yes* | Long-lived MCP token (recommended) | | BURN_SUPABASE_TOKEN | Yes* | Legacy JWT token (still supported) | | BURN_API_URL | No | Custom API URL (default: production) |

*One of BURN_MCP_TOKEN or BURN_SUPABASE_TOKEN required.

Security

Token scoped to your data only (Row Level Security)
Status flow enforced: Flame → Spark → Vault, or → Ash
Rate limit: 30 calls/min per session
Tokens expire after 30 days

License

MIT