sb-mcp #

Four-tool MCP server for SilverBullet

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

• internal/server/silverbullet.md
• internal/server/tools.go

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://tangled.org/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.toml or global ~/.config/mise/config.toml to automate updates.

• With Go 1.26.2 or newer, install from the module path:

  go install secluded.site/sb-mcp@latest
  

• 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