diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..4f614de70fc11e1b01d7661eccd861b6c6f299a5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,135 @@
+<!--
+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/)
+
+_A three-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
+
+## 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. |
+
+### `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
+```
+
+In HTTP mode, it starts a [Streamable HTTP] server on `:3001`. Note: localhost
+protection is disabled because reverse proxies (nginx, Caddy, etc.) forward the
+external `Host` header, which would otherwise trigger 403s from the SDK's DNS
+rebinding protection.
+
+[Streamable HTTP]: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http
+
+## 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.