diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ec7d9a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+## maubot-osc
+
+`maubot-osc` is a simple [maubot](https://maubot.xyz/) plugin to query an [Open Build Service](https://openbuildservice.org/) instance. Basically it replicates a few of the features of the `osc` command line tool used to interact with the OBS.
+
+### Features
+
+- Query repository status (with links to the latest build log)
+- Trigger rebuild of packages
+- Trigger source service runs
+- Works in E2EE rooms (check the [maubot docs](https://docs.mau.fi/maubot/usage/encryption.html))
+
+### Dependencies
+
+These are in addition to what maubot requires by itself.
+
+- lxml
+- jinja2
+
+### Installation
+
+Drop the .mbp file in the plugin section of your maubot web interface.
+Then you need to modify a few configuration parameters for your instance:
+
+- `api_url`: the URL to make API requests to the OBS instance. By default it points to the [public OBS instance of the openSUSE project](https://build.opensuse.org) (`https://api.opensuse.org`).
+- `instance_url`: the main URL of the Build Service instance. Defaults to `https://build.opensuse.org`.
+- `username`: A valid username for the instance
+- `password`: A password for the username. **Currently kept in cleartext**. Suggestions on how to improve this are welcome.
+- `trigger_token`: An OBS access token with the `runservice` capability. See "Creating tokens" below.
+- `rebuild_token`: An OBS access token with the `rebuild` capability. See "Creating tokens" below.
+
+### Creating tokens
+
+The [`osc`](https://en.opensuse.org/openSUSE:OSC) command line utility can generate [tokens](https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.authorization.token.html#id-1.5.10.18.4) needed for some operations (rebuild packages and triggering source services). As far as I know, there is no way to have a token with more than one supported operation, so you'll need to generate two.
+
+This assumes you have already configured `osc` to connect to your OBS instance of interest. Refer to the OSC wiki (linked above) for more information.
+
+Generate a token with the `rebuild` capability:
+
+```
+osc token --create --operation rebuild
+```
+
+And one with the `runservice` capability (default):
+
+```
+osc token --create
+```
+
+Save both tokens in the configuration. Should you need to, you can view them later by running `osc token` with no arguments.
+
+### Usage
+
+Make sure your bot instance is in a room (refer to the maubot docs for how) and then type `!osc help` for help.
+
+### Notice
+
+I made this in about three or four hours for my own use. Don't expect high quality code or a lot of polish.
+
+### License
+
+This project is licensed under the Affero GNU General Public License, version 3.0, or (at your option) any later version.