SilverBullet README

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:

bash

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:

bash

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):

config.json

{
  "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

config.json

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

Local, with no reverse proxy in front:

config.json

{
  "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

ini

[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.

Terminal

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.

bash

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