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
This repo also maintains an Agent Skill for SilverBullet. If your agent has CLI access, prefer this over the MCP server because it allows composition through shell, like piping a page to a file.
Click to expand skill installation
Copy/paste this to your agent.If you already have Agent Skills installed, mkdir "using-silverbullet" next to the other directories, then save "https://git.secluded.site/sb-mcp/blob/main/SKILL.md?raw=1" to "using-silverbullet/SKILL.md". If you do not have any other skills already, STOP and tell me.
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.