<!--
SPDX-FileCopyrightText: Amolith <amolith@secluded.site>

SPDX-License-Identifier: CC0-1.0
-->

# sb-mcp

[![Go Report Card](https://goreportcard.com/badge/git.secluded.site/sb-mcp)](https://goreportcard.com/report/git.secluded.site/sb-mcp)
[![MutuaL-1.2](https://img.shields.io/badge/License-MutuaL--1.2-af2e1a?style=flat&labelColor=110402&link=https%3A%2F%2Fcodeberg.org%2FMutualism%2FMutualist-License)](https://codeberg.org/Mutualism/Mutualist-License)
[![scratchanitch.dev badge](https://img.shields.io/badge/scratchanitch-dev-FFC4B5)](https://scratchanitch.dev)
[![REUSE status](https://api.reuse.software/badge/git.secluded.site/sb-mcp)](https://api.reuse.software/info/git.secluded.site/sb-mcp)
[![Liberapay donation status](https://img.shields.io/liberapay/receives/Amolith.svg?logo=liberapay)](https://liberapay.com/Amolith/)

_Four-tool MCP server for [SilverBullet]_

[SilverBullet]: https://silverbullet.md

## Contents

- [Why?](#why)
- [Tools](#tools)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Contributing](#contributing)

## 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.

[Space Lua]: https://silverbullet.md/Space%20Lua
[Model Context Protocol]: https://modelcontextprotocol.io

Because I always want to know, the prose your agent would receive if it
calls the `usage` tool is

- [internal/server/silverbullet.md](https://git.secluded.site/sb-mcp/blob/main/internal/server/silverbullet.md)
- [internal/server/tools.go](https://git.secluded.site/sb-mcp/blob/main/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.

[Agent Skill]: https://agentskills.io/

<details><summary>Click to expand skill installation</summary>
Copy/paste this to your agent.

<blockquote>
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.
</blockquote>
</details>

## 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][bin-latest].

[bin-latest]: https://releases.secluded.site/sb-mcp/latest

- Using [mise](https://mise.jdx.dev/) (recommended), copy the snippet from the
  releases page into your `mise.toml` or global `~/.config/mise/config.toml` to
  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

```bash
# 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](https://pr.pico.sh/r/amolith/llm-projects) on
[pr.pico.sh](https://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

```bash
# 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](https://pr.pico.sh)'s home
page for a more complete example workflow.