silverbullet-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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:
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;
reaches every space of the instance that the agent's user may access (SilverBullet ≥ 2.10 multi-space mode, spaces addressed as
/<space>);returns a page rendered, as Markdown with
${…}expressions, queries, templates and transclusions evaluated, and as a screenshot (PNG), next to the raw source;keeps the revision-guarded
edit-notewithdryRun, so that clients written for v1 keep working;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;
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;
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;
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 |
Architecture decision for v2, with the measurements of the Runtime API spike | |
OAuth: what the server verifies, what the identity provider must do (with Keycloak), client registration, reachability, connecting a client | |
Cloudflare Access in front of the server: what the server verifies, what the Access application must do, the route, connecting a client | |
Security model: threat model, access list, write filter, allowlist, scan, index-time transform, defaults | |
Conventions a space follows when this server guards it | |
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 | |
Measured behaviour of SilverBullet 2.12.1 that the security model rests on | |
The server: | |
The Proposals library: | |
The shipped allowlist and examples of the credentials file, the access list and the allowed-files list | |
The release checks (a compose test instance, a bootstrap through the admin API, one check per assumption, a report per SilverBullet version) and, in | |
The acceptance test of a running server, from any machine that reaches it (Acceptance test below) | |
The image ( | |
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 |
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.tsThe 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 CodeA 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, AuthenticateIn 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.tsMCP_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) |
| 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 ( |
access list |
| What each user or group may do per space and path; a folder line ( |
allowlist |
| The functions a page may call (shipped default; docs/security.md, section 6) |
allowed files |
| Non-page files the scan may ignore (example; docs/security.md, section 7) |
Variable | Default | What |
|
| The SilverBullet instance; spaces are addressed as |
|
| The listening port |
|
| Where the access list, the allowlist and the allowed-files list are, unless given one by one |
| all the scan user can see | The spaces to guard, comma-separated |
|
| The technical user of the scan (docs/security.md, section 7): the credentials-file line that holds its token |
|
| The file types the server writes (docs/security.md, section 5) |
|
| Time between scans ( |
|
|
|
|
| The report page of every guarded space, written at this page name; a path such as |
|
| The folder the proposal tools write to; the same folder as |
|
| The folder of the library's working copies ( |
|
| Tool calls per user and minute; |
|
| Runtime API calls in flight at once, over all users and spaces (Rendering below) |
|
| The most a |
|
| 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) |
|
|
|
| none | Both set: the server verifies OAuth access tokens of that issuer for that resource URL, beside static bearers (docs/oauth.md) |
| from the issuer; | Where the issuer's keys are, which claim names the user, which scopes a token must carry |
| 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 |
| those of | 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 |
|
| the target is at that revision |
|
| 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 instanceDetails, 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'sLICENSE.mdbeside them; see docs/security.md, section 5.Ahmad-A0/silverbullet-mcp (MIT, v1.2.0):
prepareEditsand its error texts are copied intosrc/edit.ts; the tool names, input schemas and the shape of the results follow itssrc/mcp-server.tsandsrc/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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Governed access to sensitive data, secrets and APIs for AI agents. A signed proof for each decision.
Publish your agent's Markdown as shareable web pages with revision provenance and comments.
Multiple Gmail accounts, editable Google Sheets & Docs for AI agents. Deny-by-default access rules.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- FlicenseNot gradedqualityDmaintenanceEnables coordinating multiple AI agents over HTTP with authenticated messaging, cached read-only Notion context, and safe proxying to registered endpoints.-
- AlicenseNot gradedqualityBmaintenanceBridges MCP clients to SilverBullet spaces over loopback, exposing page CRUD, task management, diffs, and search tools to AI agents without tunneling.MIT
- AlicenseBqualityBmaintenanceEnables 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.912 npmMIT