silverbullet-mcp

A tiny MCP server that gives any MCP-capable agent read/write access to a SilverBullet space.

No dependencies — Python 3 stdlib only. It is a translator: it forwards MCP tool calls to SilverBullet's built-in /.fs HTTP API, which already supports read, write and delete. Nothing needs to be installed or patched inside SilverBullet.

It is small enough to read in one sitting, and it speaks both MCP transports that clients actually use: stdio (spawned by Claude Desktop, Cursor, and friends) and streamable HTTP (shared or remote access behind a reverse proxy).

Quick start

Run it as a server:

git clone https://github.com/wicahma/silverbullet-mcp.git
cd silverbullet-mcp
cp .env.example .env      # set MCP_TOKEN, and SB_URL if SilverBullet is elsewhere
set -a; . ./.env; set +a
python3 sb_mcp.py         # streamable HTTP on http://127.0.0.1:9339/mcp

Or let a client spawn it — no clone required, since it ships on npm:

SB_URL=http://127.0.0.1:8123 npx -y silverbullet-mcp --stdio

Tools

| Tool | Arguments | What it does | |---|---|---| | list_pages | — | list every markdown page | | read_note | path | read a page | | write_note | path, content | create or overwrite a page | | append_note | path, content | append, creating the page if absent | | delete_note | path | delete a page | | search_notes | query | case-insensitive substring search, returns path:line: text |

Paths are space-relative (Projects/Foo.md), restricted to .md, and .. segments are rejected.

Transports

| | stdio | streamable HTTP | |---|---|---| | Start | --stdio, or MCP_STDIO=1 | default | | Framing | newline-delimited JSON-RPC on stdin/stdout | POST /mcp | | Auth | none — the client already owns the process | Authorization: Bearer $MCP_TOKEN | | Good for | Claude Desktop, Cursor, any client that spawns the server | remote or shared access, reverse proxies, several clients |

Both come from the same code and expose the same six tools. MCP_TOKEN only matters in HTTP mode; the SB_* variables describe the upstream space in both.

Client setup

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "silverbullet": {
      "command": "npx",
      "args": ["-y", "silverbullet-mcp", "--stdio"],
      "env": { "SB_URL": "http://127.0.0.1:8123" }
    }
  }
}

Cursor

Same body, in .cursor/mcp.json for one project or ~/.cursor/mcp.json globally.

Any client that speaks remote MCP

{
  "mcpServers": {
    "silverbullet": {
      "type": "http",
      "url": "https://your-host.example/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

Local, with no reverse proxy in front:

{
  "mcpServers": {
    "silverbullet": {
      "type": "http",
      "url": "http://127.0.0.1:9339/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

Note for remote clients: url must be, or must proxy to, this bridge — not SilverBullet itself. SilverBullet has no MCP endpoint of its own; that is what this project adds.

Configuration

All configuration is environment variables, so the same code runs for anyone.

| Variable | Default | Meaning | |---|---|---| | MCP_TOKEN | (empty) | Required in HTTP mode. Bearer token clients must send. Generate with python3 -c "import secrets; print(secrets.token_urlsafe(32))" | | SB_URL | http://127.0.0.1:8123 | SilverBullet base URL. Must expose /.fs | | SB_AUTH_TOKEN | (empty) | Optional. Sent to SilverBullet as Authorization: Bearer ... | | SB_USER_AGENT | silverbullet-mcp/1.0 | Sent on upstream calls. Some CDNs answer Python's default urllib signature with 403 / error 1010 | | MCP_HOST | 127.0.0.1 | Bind address | | MCP_PORT | 9339 | Bind port | | MCP_STDIO | (unset) | Any value switches to stdio, same as --stdio |

HTTP endpoints

• POST /mcp — JSON-RPC 2.0. Bearer token required. A notification returns 202.
• GET /health (also GET /mcp/health) — {"status":"ok"}, no auth, no internal details.

Protocol versions negotiated: 2024-11-05, 2025-03-26, 2025-06-18. Maximum request body 4 MB. Batch arrays are accepted.

Auth

The bearer token is the gate. Fail closed: if MCP_TOKEN is set, every request without a matching token is rejected. If it is unset the server still starts (for local debugging) but logs a loud warning.

Do not expose this server to the internet without a token. Anyone who can reach /mcp can read, overwrite and delete every page in the space.

SilverBullet's own auth

Setting SB_AUTH_TOKEN alone on recent SilverBullet builds (verified on the 2.10.0 Rust build) does not enable authentication — anonymous requests still succeed. Per upstream docs the token is only an alternative bearer path; the server actually enforces auth when SB_USER is configured. If in doubt, probe your own instance with a deliberately wrong bearer token: if it still returns 200, auth is off.

Practical consequence: put the token gate at this bridge (or at your reverse proxy), not at SilverBullet.

Deployment

systemd user unit

[Unit]
Description=SilverBullet MCP bridge
After=network-online.target

[Service]
EnvironmentFile=%h/silverbullet-mcp.env
WorkingDirectory=%h/silverbullet-mcp
ExecStart=/usr/bin/python3 sb_mcp.py
Restart=on-failure

[Install]
WantedBy=default.target

Keep the env file mode 600.

Behind a reverse proxy

Works fine behind Cloudflare Tunnel, nginx, Caddy, etc. Two notes from real deployments, both learned the hard way:

• Route by path on an existing hostname if you are on a free TLS plan: some providers issue certificates for the apex and a single subdomain level only, so a two-level hostname may fail the TLS handshake. A path route on an already-covered host avoids that entirely.
• Machine clients cannot complete SSO. If your host sits behind an identity-aware proxy (Cloudflare Access and similar), bypass the MCP path and let the bearer token be the gate. This is the usual split: the SilverBullet UI and its /.fs API stay behind SSO, while /mcp is public but token-gated.

Troubleshooting

| Symptom | Cause | |---|---| | 401 unauthorized | Missing or wrong MCP_TOKEN in the client's header | | 403 with error code: 1010 | A CDN/WAF rejected the upstream request signature. Set SB_USER_AGENT to an identifying value, and allow machine clients on the API path | | Upstream replies with an HTML sign-in page, or the bridge reports JSONDecodeError | SB_URL points at a UI that is behind SSO. Point it at an address where /.fs is actually reachable (localhost, or an internal hostname) | | HttpError 500 / 502 mentioning upstream | The bridge is fine; SilverBullet is down or SB_AUTH_TOKEN is wrong | | Tools missing in the client after editing config | Restart the client — MCP servers are connected at startup | | npx exits immediately | python3 is not on PATH; the npm wrapper is only a launcher for sb_mcp.py |

Security notes

• Paths are restricted to .md and .. traversal segments are rejected.
• write_note overwrites with no revision history.
• Binds to loopback by default; the reverse proxy is the sole ingress.
• search_notes reads every page on each call. There is no index.
• The bridge stores nothing. It holds no state beyond the environment it was started with, so a restart is always safe.

Distribution

Published as an npm package and as an agent plugin from this same repository.

npm publish --access public     # package "silverbullet-mcp"

server.json is the official MCP Registry entry (schema 2025-12-11): the npm package, run over stdio. It deliberately declares no remote endpoint — that is each deployment's own URL, so add a remotes entry if you want yours listed.

brew install mcp-publisher
mcp-publisher login github
mcp-publisher validate          # validates server.json
mcp-publisher publish

The registry name is reverse-DNS and must match the publishing GitHub account: replace OWNER in server.json ("name") and package.json ("mcpName") with your GitHub login before publishing — the two must be identical.

Agent plugin manifests live at .zcode-plugin/plugin.json (ZCode) and .claude-plugin/plugin.json + .claude-plugin/marketplace.json (Claude Code and the skills.sh layout). The plugin ships the MCP server plus skills/silverbullet-mcp/, and reads the bearer token from the client's user config as mcp_token, so no secret is stored in the repository.

License

MIT