mcp-server-silverbullet

English · 한국어

An MCP server that connects a SilverBullet space over its HTTP filesystem API (/.fs) and exposes only a chosen prefix to AI agents. It provides five tools plus resources, so you can attach your notes to an agent without handing over the whole space. Runs with npx — no install needed.

Features

• Prefix scoping — the agent sees only what lives under one prefix (the folder's contents plus its namesake page). Enforced in code, not in the prompt.
• Scope gating — allow read only, or add write / delete. Tools that aren't allowed are never registered in the first place.
• Path hardening — absolute paths, .., encoded traversal, and anything outside the prefix are all rejected.
• Token isolation — the SilverBullet token stays in the server environment and is never exposed to the LLM.

Note — this is a guardrail for the LLM, not a multi-tenant security boundary. SilverBullet's SB_AUTH_TOKEN grants full space access (there are no prefix-scoped tokens), so use it only in an environment you control.

Setup

Requires Node.js ≥ 20 and a SilverBullet instance with SB_AUTH_TOKEN configured.

Add the following to your MCP client (Claude Code, Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "silverbullet": {
      "command": "npx",
      "args": ["-y", "@bong-u/mcp-server-silverbullet@0.1.0"],
      "env": {
        "SILVERBULLET_MCP_BASE_URL": "https://notes.example.com",
        "SILVERBULLET_MCP_TOKEN": "<SB_AUTH_TOKEN>",
        "SILVERBULLET_MCP_PREFIX": "projects/work",
        "SILVERBULLET_MCP_SCOPES": "read"
      }
    }
  }
}

Variable	Required	Default	Description
SILVERBULLET_MCP_BASE_URL	✅	—	SilverBullet instance URL.
SILVERBULLET_MCP_TOKEN	✅	—	SB_AUTH_TOKEN. Never passed to the LLM.
SILVERBULLET_MCP_PREFIX	—	whole space	Subpath the agent may access, e.g. projects/work.
SILVERBULLET_MCP_SCOPES	—	read,write,delete	Allowed operations (must include read).
SILVERBULLET_MCP_TIMEOUT_MS	—	15000	Request timeout (ms).
SILVERBULLET_MCP_MAX_SEARCH_BYTES	—	1000000	Max file size search_files will scan.
SILVERBULLET_MCP_USER_AGENT	—	mcp-server-silverbullet/<version>	User-Agent sent upstream.

If a required variable is missing or malformed, the server exits immediately with a clear error.

Tools

Paths keep the prefix's top segment (notes.md, notes/todo.md). Feed a path returned by list_files straight into read_file.

Tool	Scope	Description
list_files	read	List files under the prefix (optionally within a subpath).
read_file	read	Read a file — text as utf8, binary as base64.
write_file	write	Create or replace a file.
delete_file	delete	Delete a file.
search_files	read	Substring search over file names and text content.

Files are also exposed as resources: silverbullet://notes/todo.md.

Development

npm install
cp .env.example .env    # fill in instance URL + token
npm run dev             # run straight from source (tsx), loading .env

npm run lint            # biome
npm run typecheck       # tsc --noEmit
npm test                # vitest
npm run build           # compile to dist/

CI runs lint · typecheck · test · build on Node 20, 22, and 24.

License

MIT