sb-mcp
Four-tool MCP server for SilverBullet
Contents
Why?
SilverBullet is a note-taking/knowledge-management tool with a powerful Runtime API that can execute Space Lua, take screenshots, and surface console logs.
sb-mcp wraps the Runtime API in a Model Context Protocol server so coding agents can read and write notes, run queries, debug plug failures, and generally treat your SilverBullet space as a first-class workspace.
Because I always want to know, the prose your agent would receive if it
calls the usage tool is
Tools
| Tool | Description |
|---|---|
execute_lua |
Run a Space Lua script on the SilverBullet instance. |
screenshot |
Capture the current SilverBullet viewport as a PNG image. |
console_logs |
Retrieve recent console log entries from SilverBullet for debugging. |
usage |
Load the full SilverBullet usage guide (Space Lua syntax, APIs, gotchas). |
execute_lua parameters
| Parameter | Type | Description |
|---|---|---|
script |
string | The script to execute. |
timeout |
int | Maximum execution time in seconds (1–21600, default 120). |
console_logs parameters
| Parameter | Type | Description |
|---|---|---|
limit |
int | Maximum number of log entries to return (1–1000, default 100). |
since |
int | Only return entries newer than this unix millisecond timestamp. |
Installation
Pre-built binaries are available at releases.secluded.site/sb-mcp/latest.
- Using mise (recommended), copy the snippet from the
releases page into your
mise.tomlor global~/.config/mise/config.tomlto automate updates. - Without mise, or a similar tool, download the binary for your platform from
the releases page and place it somewhere in your
$PATH.
Configuration
All configuration is through environment variables and command-line flags.
| Variable | Required | Description |
|---|---|---|
SB_URL |
yes | Base URL of your SilverBullet instance (e.g. https://notes.example.com). |
SB_TOKEN |
no | Bearer token for Authorization header. |
SB_USER |
no | Username for cookie-based session auth (used with SB_PASS). |
SB_PASS |
no | Password for cookie-based session auth (used with SB_USER). |
SB_TIMEOUT |
no | Default Lua execution timeout in seconds (default 120). |
SB_TOKEN and SB_USER/SB_PASS don't override each other and can be set
simultaneously. This is helpful if your instance is behind some kind of
authenticating proxy: the token can get you through the proxy and user/pass get
you into the instance.
Usage
# stdio
SB_URL=https://notes.example.com sb-mcp serve
# http
SB_URL=https://notes.example.com sb-mcp serve --http :3001
Contributing
Patch requests are in
amolith/llm-projects on
pr.pico.sh. You don't need a new account to contribute,
you don't need to fork this repo, you don't need to fiddle with git send-email, you don't need to faff with your email client to get git request-pull working...
You just need:
- Git
- SSH
- An SSH key
# Clone this repo, make your changes, and commit them
# Create a new patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
# After potential feedback, submit a revision to an existing patch request with
git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
# List patch requests
ssh pr.pico.sh pr ls amolith/llm-projects
See "How do Patch Requests work?" on pr.pico.sh's home page for a more complete example workflow.