← Handbook

Claude integration

Markdown written in Claude — an artifact, a chat answer, a file produced by Claude Code — can go straight into your markbird library without a copy-paste round trip and without uploading anything.

There is one entry point and three ways to reach it. Pick the one that matches where you work:

How the handoff works

Everything above ends up opening one kind of link:

https://app.markbird.md/new#<payload>

<payload> is your document — gzip-compressed and base64url-encoded — carried in the URL fragment, the part after the #.

That detail is the whole point. Browsers never transmit the fragment: it is not in the request, not in server logs, not in the Referer header sent to the next site you visit. A feature whose job is moving your writing around would be a strange place for markbird to start uploading it, so it does not. The import happens entirely in your browser, which also means it works offline and needs no account.

Two consequences worth knowing:

• markbird strips the payload from the address bar before the editor appears, so reloading the page is a reload, not a second copy of the document.
• A URL cannot hold an unlimited amount of text. Very large documents are refused with a clear message rather than silently truncated — see Troubleshooting.

MCP server

The MCP server covers Claude Desktop and Claude Code with one component. Both speak the Model Context Protocol; a browser extension cannot reach either, because Claude Desktop does not load browser extensions.

Setup

Build it from the repository, then register it:

pnpm --filter @markbird/mcp build
claude mcp add markbird -- node /absolute/path/to/packages/mcp/dist/server.js

For Claude Desktop, add the same command to your MCP server configuration.

Using it

Ask in plain language:

Send this to markbird.

Claude calls the open_in_markbird tool, and the document opens in your library — titled, or with a title derived from its first heading if you do not give one.

Options

MARKBIRD_NO_LAUNCH is for places with no browser to open — a remote Claude Code session, or a container. You get the link back as text and open it yourself.

Browser extension

For claude.ai in a browser, the extension adds a Send to markbird button to assistant messages, and a context-menu item for any text you select. The same extension is markbird's web clipper: its toolbar button saves whatever page you are reading into your library.

Setup

pnpm --filter @markbird/extension build

Then load it into your browser:

• Chrome, Edge, Brave, Arc — open chrome://extensions, enable Developer mode, choose Load unpacked, and select packages/extension/dist.
• Firefox 140 or newer — open about:debugging#/runtime/this-firefox, choose Load Temporary Add-on, and select packages/extension/dist-firefox/manifest.json.

To send to a self-hosted markbird or to a local development build, set the address in the extension's options.

How it reads the document

The extension converts the rendered page back to Markdown rather than digging into Claude's internals. Headings, fenced code with their language, lists, tables, links, blockquotes and emphasis all survive the round trip.

It offers two triggers on purpose, because they break differently:

• Selecting text and using the context menu depends on nothing specific to claude.ai. This path keeps working through any redesign of the site.
• The button on each message is the nicer one click, but it has to find messages in the page. If Claude ships a redesign, the button may disappear until the extension is updated — the context menu carries on regardless.

Clipping any page

The toolbar button — or Clip this page to markbird / Clip selection to markbird in the context menu — turns the page you are reading into a note. The article is kept and the navigation around it is not (the same rule as importing an .html file), with the address and the date recorded in frontmatter:

---
source: 'https://example.com/post'
clipped: 2026-09-19
tags: [clipped]
---

Permissions

The extension asks for context menus, storage for your markbird address, claude.ai for the message button, and activeTab + scripting for clipping. activeTab is the point: the browser grants access to a page only in the moment you click, so the extension cannot read anything you browse otherwise, and nothing you clip is uploaded anywhere.

Files on disk

If Claude Code writes .md files locally, you do not need any of the above. Install markbird as an app (see Getting started) and it registers as a handler for .md, .markdown, .mkd and .txt. "Open with markbird" then works from your file manager.

For files you want to keep editing in place, use Open file from disk… and Save to file — markbird writes back to the real file.

Privacy

Nothing in this integration sends your documents to markbird's servers or anyone else's:

• The document travels in a URL fragment, which is never transmitted.
• The import runs in your browser and works offline.
• No account is required.
• The extension can only see claude.ai.

If you are signed in for sync, an imported document then syncs like any other document you write — that is the sync you switched on, not something this feature does on its own. See Privacy & data.

Troubleshooting

"Document is too large to hand over through a URL." Browsers limit URL length. Save the document as a .md file and use markbird's import instead, or split it.

The button does not appear on claude.ai. Claude changed its page structure. Select the text and use the right-click menu instead — that path does not depend on the site's markup — and update the extension when a new build is available.

Nothing happens when Claude says it sent the document. Check that the MCP server is registered (claude mcp list). If you are on a remote or containerized session, there is no browser to open: set MARKBIRD_NO_LAUNCH=1 and open the returned link yourself.

It opened the wrong markbird. Set MARKBIRD_URL for the MCP server, or the address in the extension's options.