Skip to main content
Glama
silverbullet-mcp

silverbullet-mcp

by finestream

silverbullet-mcp-server

An MCP server for a SilverBullet instance in multi-space mode: several agents, each acting as its own SilverBullet user, every space that user may reach, and pages rendered the way SilverBullet shows them.

Goals

One MCP server for a whole SilverBullet instance that, beyond reading and writing pages:

  1. serves several agents, each with its own credential and its own SilverBullet user, and acts towards SilverBullet as that user, so that SilverBullet's permissions decide what is allowed and every write stays attributable to a user;

  2. reaches every space of the instance that the agent's user may access (SilverBullet ≥ 2.10 multi-space mode, spaces addressed as /<space>);

  3. returns a page rendered, as Markdown with ${…} expressions, queries, templates and transclusions evaluated, and as a screenshot (PNG), next to the raw source;

  4. keeps the revision-guarded edit-note with dryRun, so that clients written for v1 keep working;

  5. runs behind a reverse proxy with secrets from files, and verifies OAuth tokens of an external identity provider, or the assertions of Cloudflare Access in front of it, beside static bearers;

  6. restricts each agent further than SilverBullet does, by path, with a deny-by-default access list per user and group that never widens what SilverBullet grants and applies to every tool, listings and search included;

  7. keeps code out of the pages agents write, so that a page an agent wrote can be opened and rendered by any person without running anything but audited code;

  8. is MIT, with code taken only from MIT, Apache or BSD sources.

It replaces a set-up of one single-user MCP server per user per space, called v1 in these documents (Ahmad-A0/silverbullet-mcp, one instance per identity): there, every additional identity costs one more container, and pages come back only as raw source, so queries do not show their results. How the server meets the goals is in docs/architecture.md.

Related MCP server: Agent Coordination Hub

The security challenge

SilverBullet runs code from content: every Space Lua block and every ${…} expression on any page runs in the browser of the person who opens the page, with that person's rights. An agent that can write one page can plant code that reads or writes everything, and a path-based access list does not close this: it decides where an agent may write, not what the written page may do. The server therefore keeps code out of the pages agents write and confines it to Library/, with configuration in CONFIG; the full model, and the terms user, person, agent and operator as these documents use them, are in docs/security.md.

Posture

The server ships strict: a deny-by-default access list, a write filter on every write with an allowlist of the functions a page may call, a scan of the space in report-only mode, an index-time transform in CONFIG that keeps blocks outside CONFIG and Library/ from loading, a refusal to serve while any of these is missing, and no rendering in a space where the scan has findings. Every part but the last two can be relaxed (write access to Library/, more allowlist entries, more file types, scan off or in quarantine mode), and the server reports a relaxed setting once at start, in its log and on its report page in the space (docs/security.md, section 11). The rules, the defaults that enforce them, and what relaxing each one accepts are in docs/space-guidelines.md; how the controls work is in docs/security.md.

Status

The server in src/ serves the thirteen tools below as the authenticated user, with the credentials file, the access list, the write filter (in a worker thread with a time limit, transclusion rule included), the scan with its report page, the refusal to serve, and the two render tools over SilverBullet's Runtime API with the render check. The client guide and the acceptance test below are the deployment material. Authentication is by static bearer, by OAuth access token of an external identity provider (docs/oauth.md; built and tested against a test issuer, not yet run against a real identity provider), or by the assertion Cloudflare Access adds to a request it let through (docs/cloudflare-access.md; built and tested against a test team domain). An agent proposes a change to a page it may not write with the three proposal tools, and a person reviews and applies it with the library in library/ (docs/proposals.md). The architecture and the security model are in docs/; the release checks in test/ assert, per SilverBullet release, the behaviour the design relies on.

What is here

Path

What

docs/architecture.md

Architecture decision for v2, with the measurements of the Runtime API spike

docs/oauth.md

OAuth: what the server verifies, what the identity provider must do (with Keycloak), client registration, reachability, connecting a client

docs/cloudflare-access.md

Cloudflare Access in front of the server: what the server verifies, what the Access application must do, the route, connecting a client

docs/security.md

Security model: threat model, access list, write filter, allowlist, scan, index-time transform, defaults

docs/space-guidelines.md

Conventions a space follows when this server guards it

docs/proposals.md

Design of change proposals: tools with which an agent proposes a change to a page it may not write, and the library with which a person reviews and applies it

docs/facts/

Measured behaviour of SilverBullet 2.12.1 that the security model rests on

src/

The server: main.ts (entry, --scan, --hash), config.ts (the environment, the watched configuration files), server.ts (HTTP, auth), oauth.ts and cf-access.ts (the two verifiers, sharing jwt.ts), tools.ts (the tools), sb.ts (SilverBullet's file, configuration and Runtime APIs), filter/ (the write filter on the vendored parser, its worker, the allowlist), access.ts, credentials.ts, scan.ts (the scan and the report page), state.ts (the refuse-to-serve and render-block state), render.ts (the render path over the Runtime API, the render check), edit.ts, match.ts (user regexes in a worker), log.ts; unit tests beside the code

library/

The Proposals library: Proposals.md is the page to install as Library/Finestream/Proposals, from the Library Manager (the repository index of finestream/silverbullet-libraries links to it, so Library: Update takes a new version), built from library/src/ by npm run build:library (CI checks that it is up to date); its documentation and configuration are on that page

config/

The shipped allowlist and examples of the credentials file, the access list and the allowed-files list

test/

The release checks (a compose test instance, a bootstrap through the admin API, one check per assumption, a report per SilverBullet version) and, in test/server/, the server's integration tests against the same instance; in test/library/, the tests of the Proposals library in a browser client (npm run test:library)

scripts/acceptance.ts

The acceptance test of a running server, from any machine that reaches it (Acceptance test below)

Dockerfile, compose.example.yaml

The image (node:24-alpine, non-root) and how to run it next to SilverBullet with secrets from files

.github/workflows/ci.yml

Lint, unit and integration tests, the check and the browser tests of the Proposals library, and a build of the image on every pull request; the image is pushed to ghcr.io/finestream/silverbullet-mcp-server on a version tag

Run

Needs Node.js 24 or newer (it runs the .ts files directly) and a SilverBullet instance in multi-space mode, 2.12 or newer.

npm install
MCP_CREDENTIALS_FILE=./secrets/credentials MCP_CONFIG_DIR=./config SB_URL=http://127.0.0.1:3000 node src/main.ts

The server listens on PORT (default 4000): POST /mcp is the MCP endpoint (streamable HTTP, stateless, bearer in the Authorization header), GET /healthz the health check, and, with OAuth configured, GET /.well-known/oauth-protected-resource its metadata. Clients that speak only stdio reach it through mcp-remote with the bearer as a header. The image does the same: see compose.example.yaml.

Two more modes: node src/main.ts --scan runs one scan over the guarded spaces and exits with 1 on findings (the installation step of docs/security.md, section 7); printf '%s' "$SECRET" | node src/main.ts --hash prints the SHA-256 of a client secret for the credentials file.

Clients

The server speaks MCP over streamable HTTP: POST https://<host>/mcp with the client's bearer in the Authorization header. A client that speaks HTTP itself needs no helper:

claude mcp add --scope user --transport http notes https://mcp.example.org/mcp --header "Authorization: Bearer $BEARER"   # Claude Code

A client that speaks only stdio, such as the Claude desktop app, reaches it through mcp-remote. The bearer goes into an environment variable, because the app does not pass arguments with spaces reliably:

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.example.org/mcp", "--header", "Authorization:${AUTH_HEADER}", "--transport", "http-only"],
      "env": { "AUTH_HEADER": "Bearer <the client's bearer>" }
    }
  }
}

One bearer per client (printf '%s' "$BEARER" | node src/main.ts --hash gives the hash for the credentials file); a scheduled or unattended run uses the connector of the app it runs in, with that connector's bearer. A client never holds a SilverBullet API token.

With OAuth (MCP_OAUTH_ISSUER and MCP_OAUTH_RESOURCE set) a client connects by URL and the user logs in at the identity provider; no bearer is handed around and no mcp-remote is needed:

claude mcp add --scope user --transport http notes https://mcp.example.org/mcp --client-id <client id> --callback-port 8765   # Claude Code; then /mcp, Authenticate

In Claude on the web, desktop and mobile: Settings → Connectors → Add custom connector, with the server's URL. Which client ID to enter, which redirect URIs the identity provider must allow, and from where each client must reach the server are in docs/oauth.md, sections 3 to 5. Static bearers keep working beside it.

Through Cloudflare Access (MCP_CF_ACCESS_TEAM_DOMAIN and MCP_CF_ACCESS_AUD set) a hosted client connects by the public URL and the user logs in at Access, which is then the only thing reachable from the internet; the user's line in the credentials file names the e-mail address Access signs in (docs/cloudflare-access.md). The other ways in keep working beside it, by a route that does not pass Access.

Acceptance test

scripts/acceptance.ts checks a running server from any machine that reaches it, as one user, and prints PASS or FAIL per check: a wrong bearer is refused with 401 and /healthz answers; list-spaces shows the spaces with the effective rights; a denied page is absent from listings and search and refused on read by the access list; a page is read raw with its revision; render-note and screenshot-note are either evaluated (a PNG) or refused by the access list, as MCP_EXPECT_RENDER says; a write outside the user's area is refused by the access list; a page with a space-lua block inside it is refused by the write filter with rule and line; a stale edit-note is rejected and the current revision accepted; the report page shows serving, a scan and no findings. It writes one page under MCP_WRITE_AREA and deletes it again where the user may.

npm ci
MCP_URL=https://mcp.example.org/mcp MCP_BEARER=… MCP_RAW_PAGE="A page with queries" MCP_SCREENSHOT_PAGE=index \
  MCP_WRITE_AREA="Shared/Bot/" MCP_DENIED_PAGE=CONFIG MCP_DENIED_TEXT="config.set" MCP_EXPECT_RENDER=no node scripts/acceptance.ts

MCP_SPACE selects a space other than the user's default; MCP_OUTSIDE_PAGE (default Acceptance outside) names a page the user may not create; MCP_REPORT_PAGE defaults to MCP Server and may be a path, like the server's setting of the same name. Exit code 0 when every check passed, 1 otherwise, 2 when the test could not run.

Configuration

Four files, the last optional, and a few variables. The files are re-read when they change; a SIGHUP re-reads them and runs a scan.

File

Variable

What

credentials (a secret)

MCP_CREDENTIALS_FILE, default /run/secrets/credentials

One line per SilverBullet user: API token, default space, groups, bearer hashes and, optionally, the e-mail addresses for Cloudflare Access; the line of the technical user (MCP_SCAN_USER, default scan) (example; docs/security.md, section 3)

access list

MCP_ACCESS_LIST_FILE, default $MCP_CONFIG_DIR/access-list

What each user or group may do per space and path; a folder line (Shared/) covers the page of the same name too, and a line for that page alone is the exception (example; docs/security.md, section 4)

allowlist

MCP_ALLOWLIST_FILE, default $MCP_CONFIG_DIR/allowlist

The functions a page may call (shipped default; docs/security.md, section 6)

allowed files

MCP_ALLOWED_FILES_FILE, default $MCP_CONFIG_DIR/allowed-files, optional

Non-page files the scan may ignore (example; docs/security.md, section 7)

Variable

Default

What

SB_URL

http://silverbullet:3000

The SilverBullet instance; spaces are addressed as /<space> below it

PORT

4000

The listening port

MCP_CONFIG_DIR

/etc/silverbullet-mcp

Where the access list, the allowlist and the allowed-files list are, unless given one by one

MCP_SPACES

all the scan user can see

The spaces to guard, comma-separated

MCP_SCAN_USER

scan

The technical user of the scan (docs/security.md, section 7): the credentials-file line that holds its token

MCP_FILE_TYPES

.md

The file types the server writes (docs/security.md, section 5)

MCP_SCAN_INTERVAL

15m

Time between scans (0: at start and on SIGHUP only)

MCP_SCAN_MODE

report

report or quarantine (docs/security.md, section 7)

MCP_REPORT_PAGE

MCP Server

The report page of every guarded space, written at this page name; a path such as Space/MCP Server puts it in a folder (docs/security.md, section 8)

MCP_PROPOSALS_DIR

Proposals/

The folder the proposal tools write to; the same folder as proposalPrefix in the library's configuration (docs/proposals.md, section 4)

MCP_WORKING_COPIES_DIR

Working copies/

The folder of the library's working copies (workingCopyPrefix), which no proposal may target; it may not lie inside the proposal folder, nor that inside it, and neither may lie in CONFIG or Library/

MCP_RATE_LIMIT

120

Tool calls per user and minute; 0 for none

MCP_RENDER_PARALLEL

4

Runtime API calls in flight at once, over all users and spaces (Rendering below)

MCP_RENDER_TIMEOUT

90s

The most a render-note or screenshot-note call may take, queue and index wait included

MCP_INDEX_WAIT

5s

How long a render waits for the runtime's index to hold a page written through the server before it reboots the runtime (docs/security.md, section 12)

MCP_LOG_LEVEL

info

info or debug; the log is JSON lines on stdout

MCP_OAUTH_ISSUER, MCP_OAUTH_RESOURCE

none

Both set: the server verifies OAuth access tokens of that issuer for that resource URL, beside static bearers (docs/oauth.md)

MCP_OAUTH_JWKS_URL, MCP_OAUTH_USER_CLAIM, MCP_OAUTH_SCOPES

from the issuer; preferred_username; none

Where the issuer's keys are, which claim names the user, which scopes a token must carry

MCP_CF_ACCESS_TEAM_DOMAIN, MCP_CF_ACCESS_AUD

none

Both set: a request that came through Cloudflare Access is authenticated by the assertion Access adds, verified against that team domain and that application's AUD tag (docs/cloudflare-access.md)

PORT, MCP_RATE_LIMIT and MCP_RENDER_PARALLEL must be whole numbers (MCP_RENDER_PARALLEL at least 1), and the durations a number with ms, s, m, h or d (plain seconds without a unit), at most 24 days; on anything else the server does not start and names the variable. A variable that is empty counts as unset and gets its default, as compose passes an unset ${VAR}. A setting weaker than the shipped default is accepted and reported once (docs/space-guidelines.md, Defaults and overrides).

Tools

list-spaces, list-notes, read-note, read-multiple-notes, search-notes, create-note, edit-note, delete-note, render-note, screenshot-note, with the names and inputs of v1 where they exist, plus a space parameter on each (default: the user's default space), and the proposal tools propose-edit, propose-delete and propose-move. edit-note needs the revision that read-note returned and has a dryRun.

Proposal tool

Arguments

What it checks before it writes the proposal page

propose-edit

those of edit-note (filename, edits, expectedRevision), reason, name, optional group

the target is at that revision; every old text occurs as often as expected, no two overlap; the resulting page passes the write filter. Answers with the diff, as the dry run of edit-note does

propose-delete

filename, expectedRevision, reason, name, optional group

the target is at that revision

propose-move

filename, newName, expectedRevision, reason, name, optional group

the target is at that revision; the user may read the new name, and nothing exists under it; the page passes the write filter there

None writes the target: each writes one proposal page, <MCP_PROPOSALS_DIR><name>, as the user, which a person reviews and applies with the library. They need r on the target, w on the proposal page and a reason that is not blank; a user who may write (or, for a delete, delete) the target is told to use edit-note (or delete-note). The target and a new name must be pages outside CONFIG, Library/, the proposal folder and the folder of the working copies. In a space without the library, or with a library of another version, only these three tools are refused, and the report page says so. The semantics, the SilverBullet calls and the rights each tool needs are in docs/architecture.md, Tool surface.

Rendering

read-note returns a page's source, as stored, with its revision; render-note returns the page as the user sees it, with ${…} expressions, query[[…]] results (as HTML tables), templates and transclusions evaluated; screenshot-note returns a PNG of the page as SilverBullet's editor shows it. Both render tools go through SilverBullet's Runtime API as the calling user, need the x right in the access list, render pages (.md) only, return no revision (edits are always based on read-note), are refused in a space where the scan has findings, and return nothing when the render loaded a page or file the user has no r on (a transclusion, an image), which the server reads off the runtime's browser after the fact. How they work, the queue per (user, space), the wait for the runtime's index after a write and the system.reboot() fallback: docs/architecture.md, section 5, and docs/security.md, section 12.

Costs. The first render of a user in a space starts a headless Chrome for that (user, space) pair inside the SilverBullet container: about 200 MiB, plus the space's index; the first call takes 2 s on a tiny space and about 9 s on a space of 1,000 pages (the runtime indexes the space before it answers), later calls tens of milliseconds (docs/architecture.md, Findings from the spike). SilverBullet keeps the runtime until it restarts or an administrator stops it (Admin → Runtimes); the server cannot start, stop or count runtimes, and lists the pairs it has used on its report page. Grant x only where the SilverBullet container's memory allows one runtime per pair that may render. The Runtime API needs Write access and the per-user Runtime API grant in SilverBullet; a read-only member cannot render.

Tests

npm run lint                                          # eslint and tsc
npm run test:unit                                     # the edit engine, the write filter, the access list, the credentials file, the verifiers
node test/instance.ts up                              # this working copy's SilverBullet instance (own project name and port), bootstrapped
npm run test:integration                              # the server against that instance, rendering included
node test/run.ts                                      # the release checks, report in test/report/<version>.md
node test/instance.ts down                            # remove the instance

Details, another SilverBullet release and a run without Docker: test/README.md.

Licence

MIT.

Code is taken only from MIT, Apache-2.0 or BSD-licensed projects and is credited here and in the file it lands in. Projects under copyleft or non-OSI licences are read for ideas only.

Attributions

  • SilverBullet (MIT): the API behaviour this server relies on was read from its source and documentation; the bootstrap of the test instance follows its multi-space Runtime API end-to-end test. Four files of its Lua parser are vendored unchanged in src/filter/vendor/silverbullet/ (lua.grammar, parse-lua.js, parse-lua.terms.js, lua_comment.js, at tag 2.12.1) with SilverBullet's LICENSE.md beside them; see docs/security.md, section 5.

  • Ahmad-A0/silverbullet-mcp (MIT, v1.2.0): prepareEdits and its error texts are copied into src/edit.ts; the tool names, input schemas and the shape of the results follow its src/mcp-server.ts and src/edit-note.ts.

  • xmatthewx/silverbullet-mcp-server (MIT): reviewed for its OAuth flow and tool surface. No code copied.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to securely read and write to an Obsidian-compatible Markdown vault with per-agent access control, audit logging, and conflict resolution.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Bridges MCP clients to SilverBullet spaces over loopback, exposing page CRUD, task management, diffs, and search tools to AI agents without tunneling.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients to read, search, outline, and inspect tasks, tags, and backlinks in a SilverBullet space through its HTTP file API, with optional page-writing tools when explicitly enabled.
      9
      12 npm
      MIT