<p align="center">
  <img src="assets/hoardo.png" alt="Hoardo" width="128" height="128">
</p>

# Hoardo MCP server

[Hoardo](https://www.hoardo.com) keeps track of what you store: numbered boxes in rooms (a basement, an attic, a
storage unit), what's in each box, and your lists for packing, lending, selling, renting, to-dos and stocktakes.

The Hoardo MCP server lets Claude, ChatGPT, Cursor and other AI apps use your Hoardo. Ask where the tent is, what's in
box 12, or to put your camping things on a packing list, and the answer comes from your own boxes.

> This repository holds documentation and install instructions only. It is not the server's source code. The server is
> hosted by Hoardo at the address below.

## Server

| | |
| --- | --- |
| Address | `https://www.hoardo.com/api/mcp` |
| Transport | Streamable HTTP |
| Sign in | OAuth 2.1 with your Hoardo account |
| Registry name | `com.hoardo/hoardo` |

### Signing in

Your AI app signs you in to Hoardo with OAuth. Hoardo's sign-in is run by Supabase Auth, and apps find it through the
protected resource metadata (RFC 9728) at
[`https://www.hoardo.com/.well-known/oauth-protected-resource/api/mcp`](https://www.hoardo.com/.well-known/oauth-protected-resource/api/mcp).
Apps register themselves (dynamic client registration), so there is no client ID or key to copy anywhere. You sign in
to Hoardo, tap Allow, and the app works as you, with what your account can see.

You need a Hoardo account. Make one at [hoardo.com](https://www.hoardo.com).

Each app you connect is listed in Hoardo under **Settings › Connected apps**, where you can disconnect it at any time.

### Good to know

- **Changes happen straight away.** When you ask your AI app to add, move or update something, Hoardo does it at once.
  There is no read-only connection: an app you connect can change your Hoardo as well as read it. Tools that only read
  are marked `readOnlyHint`, and tools that delete are marked `destructiveHint`, so apps that ask before acting can do
  so.
- **Deleted things and boxes come back** from History in the Hoardo app.
- **Rooms and whole lists can't be deleted** through the MCP server.
- **Hoardo's own AI notes about your things stay in Hoardo.** Apps don't see them.

## Connect

### Claude

1. Open **Settings › Connectors** and choose **Add custom connector**.
2. Name it `Hoardo`, paste `https://www.hoardo.com/api/mcp` and choose **Add**.
3. Choose **Connect**, sign in to Hoardo and choose **Allow**.

In Claude Code:

```bash
claude mcp add --transport http hoardo https://www.hoardo.com/api/mcp
```

Then run `/mcp` in Claude Code and sign in to Hoardo.

### ChatGPT

Custom MCP servers work in ChatGPT on the web, not in the mobile app. Which plans can add them, and whether they can
make changes, is up to OpenAI.

1. Go to **Plugins**, select the plus button, then **Add custom MCP server**.
2. Enter the name `Hoardo`. Under **Connection**, paste `https://www.hoardo.com/api/mcp` and choose **OAuth**.
3. Accept the warning and select **Create as a plugin**.
4. Install it, sign in to Hoardo and select **Allow**. In a chat, type `@` and pick Hoardo.

### Cursor

Add Hoardo to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "hoardo": {
      "url": "https://www.hoardo.com/api/mcp"
    }
  }
}
```

Open **Cursor Settings › MCP**, choose **Connect** (or **Login**) beside Hoardo, sign in to Hoardo and choose **Allow**.

### Other apps

Any app that can add a remote MCP server over Streamable HTTP with OAuth sign-in should work. Give it
`https://www.hoardo.com/api/mcp` and sign in when it asks.

## Tools

Read: only looks things up. Write: changes something. Destructive: deletes, or loses something for good.

| Tool | Kind | What it does |
| --- | --- | --- |
| `list_rooms` | Read | Lists every room you own or were invited to, with how many boxes and things each has. |
| `search_items` | Read | Searches your things by several terms at once, with where each one is and which lists it's on. |
| `get_inventory` | Read | Gets everything you've stored (or one room) in a compact form, for planning. |
| `get_room` | Read | Gets a room's boxes, with each box's number, name, place and how many things are in it. |
| `get_box` | Read | Gets one box with everything in it. |
| `get_lists` | Read | Gets your lists, with their kind and how many things are on them and ticked off. |
| `get_list_items` | Read | Gets what's on one list and what the list keeps about each thing. |
| `get_rentals` | Read | Gets rentals on your renting lists, and whether things are free on given days. |
| `add_items` | Write | Adds things to a box, up to 50 at a time. |
| `update_items` | Write | Changes things' name, quantity, price, notes, category or date. |
| `move_items` | Write | Moves things into another box, in any room. |
| `put_back_items` | Write | Puts things that are out (packed, lent, rented) back in their box. |
| `add_box` | Write | Adds a box to a room or inside another box, with the next free number if none is given. |
| `update_box` | Write | Changes a box's name, number or where it stands in the room. |
| `move_boxes` | Write | Moves boxes, with everything in them, to another room or into another box. |
| `add_room` | Write | Adds a room. |
| `rename_room` | Write | Renames a room. |
| `create_list` | Write | Makes a list of things, boxes or rooms from Hoardo and things typed by name. |
| `add_to_list` | Write | Puts things, boxes or rooms on an existing list. |
| `update_list` | Write | Renames a list, changes its kind or button word, or puts it on your public sale page. |
| `tick_on_list` | Write | Ticks things off on a list (packed, returned, sold, done or counted), or unticks them. |
| `update_list_entries` | Write | Notes what a list keeps about things: who has them, prices, due dates, deposits. |
| `count_on_list` | Write | Counts things on a stocktake list. |
| `use_counted_quantities` | Write | Sets Hoardo's quantities to what a stocktake counted. |
| `book_rental` | Write | Rents things out from a renting list, now or booked ahead. |
| `update_rental` | Write | Hands a rental over, takes it back, extends, changes or cancels it. |
| `remove_from_list` | Destructive | Takes things off a list. Things only on the list are gone with it. |
| `delete_items` | Destructive | Deletes things. They come back from History in the Hoardo app. |
| `delete_boxes` | Destructive | Deletes boxes and everything in them. They come back from History in the Hoardo app. |

The full list, with each tool's input schema, is at
[`https://www.hoardo.com/.well-known/mcp/server-card.json`](https://www.hoardo.com/.well-known/mcp/server-card.json).
Hoardo's Server Card is at
[`https://www.hoardo.com/api/mcp/server-card`](https://www.hoardo.com/api/mcp/server-card).

## Help

- Connecting Hoardo to AI apps: [hoardo.com/connect](https://www.hoardo.com/connect)
- Questions and problems: [hoardo.com/contact](https://www.hoardo.com/contact)
- Privacy: [hoardo.com/privacy-policy](https://www.hoardo.com/privacy-policy)

## License

The documentation in this repository is licensed under
[Creative Commons Attribution 4.0 International](LICENSE) (CC BY 4.0). The Hoardo name, mascot and wordmark are
Hoardo's and are not covered by this license.