mcp-server-silverbullet

npm

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