Jotbird

An MCP server for JotBird that lets any LLM publish Markdown as beautifully formatted, shareable web pages.

Write a document in conversation, publish it with one tool call, and get back a live URL. Supports full Markdown — headings, code blocks, tables, footnotes, math, task lists, and more. Update or delete pages by slug, and view or change page settings (theme, branding, visibility, password protection).

Works with Claude, ChatGPT, Gemini, and any MCP-compatible client.

Quick start

1. Get an API key

Sign in at jotbird.com, open Account Settings from the account menu, and generate a key in the API Keys section.

Your key starts with jb_ and is shown only once — copy it before closing the dialog.

2. Add to your client

{
  "mcpServers": {
    "jotbird": {
      "command": "npx",
      "args": ["-y", "mcp-server-jotbird"],
      "env": {
        "JOTBIRD_API_KEY": "jb_your_key_here"
      }
    }
  }
}

claude mcp add jotbird -e JOTBIRD_API_KEY=jb_your_key_here -- npx -y mcp-server-jotbird

JOTBIRD_API_KEY=jb_your_key_here npx mcp-proxy --shell --tunnel -- npx -y mcp-server-jotbird

{
  "mcpServers": {
    "jotbird": {
      "command": "npx",
      "args": ["-y", "mcp-server-jotbird"],
      "env": {
        "JOTBIRD_API_KEY": "$JOTBIRD_API_KEY"
      }
    }
  }
}

gemini mcp add jotbird npx -e JOTBIRD_API_KEY=jb_your_key_here -- -y mcp-server-jotbird

npx -y mcp-server-jotbird

3. Use it

Ask your LLM things like:

• "Write a blog post about X and publish it to JotBird"
• "Publish these meeting notes as a shareable page"
• "Update my published page 'my-notes' with this new section"
• "Show me all my published pages"
• "Take down the page with slug 'old-draft'"
• "Publish this at my namespace as 'project-notes'" (Pro)
• "What are the settings on my page 'my-notes'?"
• "Switch my page 'launch-plan' to the essay theme" (Pro)
• "Make my page 'resume' public so search engines can find it"
• "Password-protect my page 'board-deck'" (Pro)

Tools

publish

Publish Markdown content as a formatted web page with a shareable URL. To update an existing page, pass its slug. Pro users with a username can publish at a permanent namespaced URL by passing namespaced: true.

⚠️ slug cannot name a new page. It identifies a page you already own, so that publishing again updates it in place. If you pass a slug that matches no page on your account, it is silently ignored and the page is published at an auto-generated slug (share.jotbird.com/brave-calm-meadow) — so don't count on getting the URL you asked for. New pages get a random slug; the way to choose a URL is a namespaced page (Pro), below.

list_documents

List the user's published pages. Returns each page's title, URL, slug, expiration date, and username (for namespaced pages).

No parameters.

delete

Permanently delete a published page and its shareable URL. Cannot be undone.

get_settings

Get a published page's settings: theme, branding, visibility, tags, and expiration. The page password is write-only and never returned.

update_settings

Update a published page's settings. Only the fields you pass change; everything else is preserved. Enabling a Pro feature (non-default theme, hideBranding: true, password protection) requires a Pro subscription — any account can clear them.

At least one of theme, hideBranding, or visibility must be provided. tags are reported by get_settings but can't be changed here — set them in the web app.

Settings changes are reflected in the API immediately, but the live page can take up to about a minute to reflect a visibility change as caches refresh. Theme and branding apply right away. Turning password protection on takes effect immediately, so a page is never left readable while the change propagates.

Namespaced URLs (Pro)

Pro users with a username set in Account Settings can publish at permanent, human-readable URLs like share.jotbird.com/@username/my-page. Just ask your AI:

"Publish this at my namespace as 'project-notes'." → share.jotbird.com/@clayton-myers/project-notes

Namespaced pages never expire and keep the same URL across updates. Set your username in Account Settings at jotbird.com.

Limits

A few things worth knowing:

• The 10-page cap counts new pages. Updating a page you've already published is never blocked by it, however many you have. Publishing an 11th new page on a free account fails with a "document limit reached" error.
• update_settings is rate-limited in its own bucket, separate from publishing, so changing settings doesn't eat your publish quota. Reading (get_settings, list_documents) isn't limited at all. When you hit a limit, the tool tells you how long to wait.
• Enabling a Pro-only setting on a free account fails and names the setting, so your AI can tell you exactly what needs an upgrade. Free accounts can always clear Pro settings (theme: "default", hideBranding: false) and switch between unlisted and public.

Environment variables

Development

npm install
npm run build     # tsc → dist/
npm test          # vitest

Run the server against your account (it speaks MCP over stdio, so it will sit waiting for a client — that's what a successful start looks like):

JOTBIRD_API_KEY=jb_your_key node dist/index.js

Point it at a different backend with JOTBIRD_API_URL.

License

MIT