1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# sb-mcp
8
9[](https://goreportcard.com/report/git.secluded.site/sb-mcp)
10[](https://codeberg.org/Mutualism/Mutualist-License)
11[](https://scratchanitch.dev)
12[](https://api.reuse.software/info/git.secluded.site/sb-mcp)
13[](https://liberapay.com/Amolith/)
14
15_Four-tool MCP server for [SilverBullet]_
16
17[SilverBullet]: https://silverbullet.md
18
19## Contents
20
21- [Why?](#why)
22- [Tools](#tools)
23- [Installation](#installation)
24- [Configuration](#configuration)
25- [Usage](#usage)
26- [Contributing](#contributing)
27
28## Why?
29
30SilverBullet is a note-taking/knowledge-management tool with a powerful Runtime
31API that can execute [Space Lua], take screenshots, and surface console logs.
32
33sb-mcp wraps the Runtime API in a [Model Context Protocol] server so coding
34agents can read and write notes, run queries, debug plug failures, and generally
35treat your SilverBullet space as a first-class workspace.
36
37[Space Lua]: https://silverbullet.md/Space%20Lua
38[Model Context Protocol]: https://modelcontextprotocol.io
39
40Because I always want to know, the prose your agent would receive if it
41calls the `usage` tool is
42
43- [internal/server/silverbullet.md](https://git.secluded.site/sb-mcp/blob/main/internal/server/silverbullet.md)
44- [internal/server/tools.go](https://git.secluded.site/sb-mcp/blob/main/internal/server/tools.go)
45
46This repo also maintains an [Agent Skill] for SilverBullet. If your agent has
47CLI access, prefer this over the MCP server because it allows composition
48through shell, like piping a page to a file.
49
50[Agent Skill]: https://agentskills.io/
51
52<details><summary>Click to expand skill installation</summary>
53Copy/paste this to your agent.
54
55<blockquote>
56If 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.
57</blockquote>
58</details>
59
60## Tools
61
62| Tool | Description |
63| -------------- | ------------------------------------------------------------------------- |
64| `execute_lua` | Run a Space Lua script on the SilverBullet instance. |
65| `screenshot` | Capture the current SilverBullet viewport as a PNG image. |
66| `console_logs` | Retrieve recent console log entries from SilverBullet for debugging. |
67| `usage` | Load the full SilverBullet usage guide (Space Lua syntax, APIs, gotchas). |
68
69### `execute_lua` parameters
70
71| Parameter | Type | Description |
72| --------- | ------ | --------------------------------------------------------- |
73| `script` | string | The script to execute. |
74| `timeout` | int | Maximum execution time in seconds (1–21600, default 120). |
75
76### `console_logs` parameters
77
78| Parameter | Type | Description |
79| --------- | ---- | --------------------------------------------------------------- |
80| `limit` | int | Maximum number of log entries to return (1–1000, default 100). |
81| `since` | int | Only return entries newer than this unix millisecond timestamp. |
82
83## Installation
84
85Pre-built binaries are available at
86[releases.secluded.site/sb-mcp/latest][bin-latest].
87
88[bin-latest]: https://releases.secluded.site/sb-mcp/latest
89
90- Using [mise](https://mise.jdx.dev/) (recommended), copy the snippet from the
91 releases page into your `mise.toml` or global `~/.config/mise/config.toml` to
92 automate updates.
93- Without mise, or a similar tool, download the binary for your platform from
94 the releases page and place it somewhere in your `$PATH`.
95
96## Configuration
97
98All configuration is through environment variables and command-line flags.
99
100| Variable | Required | Description |
101| ------------ | -------- | -------------------------------------------------------------------------- |
102| `SB_URL` | **yes** | Base URL of your SilverBullet instance (e.g. `https://notes.example.com`). |
103| `SB_TOKEN` | no | Bearer token for `Authorization` header. |
104| `SB_USER` | no | Username for cookie-based session auth (used with `SB_PASS`). |
105| `SB_PASS` | no | Password for cookie-based session auth (used with `SB_USER`). |
106| `SB_TIMEOUT` | no | Default Lua execution timeout in seconds (default 120). |
107
108`SB_TOKEN` and `SB_USER`/`SB_PASS` don't override each other and can be set
109simultaneously. This is helpful if your instance is behind some kind of
110authenticating proxy: the token can get you through the proxy and user/pass get
111you into the instance.
112
113## Usage
114
115```bash
116# stdio
117SB_URL=https://notes.example.com sb-mcp serve
118
119# http
120SB_URL=https://notes.example.com sb-mcp serve --http :3001
121```
122
123## Contributing
124
125Patch requests are in
126[amolith/llm-projects](https://pr.pico.sh/r/amolith/llm-projects) on
127[pr.pico.sh](https://pr.pico.sh). You don't need a new account to contribute,
128you don't need to fork this repo, you don't need to fiddle with `git
129send-email`, you don't need to faff with your email client to get `git
130request-pull` working...
131
132You just need:
133
134- Git
135- SSH
136- An SSH key
137
138```bash
139# Clone this repo, make your changes, and commit them
140# Create a new patch request with
141git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
142# After potential feedback, submit a revision to an existing patch request with
143git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
144# List patch requests
145ssh pr.pico.sh pr ls amolith/llm-projects
146```
147
148See "How do Patch Requests work?" on [pr.pico.sh](https://pr.pico.sh)'s home
149page for a more complete example workflow.