# shelf-nu-mcp

MCP server for self-hosted [shelf.nu](https://github.com/Shelf-nu/shelf.nu) instances. It lets Claude search and manage assets, custody, locations, kits and bookings.

It talks to Shelf's `/api/mobile/*` REST API, the same one the official companion app uses. It logs in with your Shelf email and password and refreshes the session automatically. A few kit features exist only in the web app, so for those it submits the web forms with a cookie session.

## Requirements

- Node.js 20+
- A Shelf account with password login. Use a dedicated user with only the role it needs: the server can do anything that user can.

## Install in Claude

### Claude Code

```sh
claude mcp add shelf -s user \
  -e SHELF_URL=https://storage.takeoff-pdm.de \
  -e SHELF_EMAIL=you@example.com \
  -e SHELF_PASSWORD='your-password' \
  -- npx -y github:takeoff-pdm/shellf-nu-mcp
```

Run `/mcp` in Claude Code to check that `shelf` is connected.

### Claude Desktop

Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:

```json
{
  "mcpServers": {
    "shelf": {
      "command": "npx",
      "args": ["-y", "github:takeoff-pdm/shellf-nu-mcp"],
      "env": {
        "SHELF_URL": "https://storage.takeoff-pdm.de",
        "SHELF_EMAIL": "you@example.com",
        "SHELF_PASSWORD": "your-password"
      }
    }
  }
}
```

### From a local checkout

```sh
git clone git@github.com:takeoff-pdm/shellf-nu-mcp.git
cd shellf-nu-mcp && npm install    # also builds dist/
claude mcp add shelf -s user -e SHELF_EMAIL=… -e SHELF_PASSWORD=… -- node "$PWD/dist/index.js"
```

## Configuration

| Env var          | Required | Description                                                                 |
| ---------------- | -------- | --------------------------------------------------------------------------- |
| `SHELF_EMAIL`    | yes      | Shelf login email                                                           |
| `SHELF_PASSWORD` | yes      | Shelf login password                                                        |
| `SHELF_URL`      | no       | Instance URL (default `https://storage.takeoff-pdm.de`)                     |
| `SHELF_ORG_ID`   | no       | Default workspace. Without it, your last-selected or personal one is used   |

Credentials are only read from the environment. Never commit them.

## Tools

- **Account:** `shelf_whoami`, `shelf_set_workspace`, `shelf_dashboard`
- **Assets:** list, get, create, update, delete, add note, change location, adjust quantity, manage placements, upload image, look up a QR code or barcode, link a QR code
- **Reference data:** locations, categories, tags (+ create), custom fields, team members
- **Custody:** assign or release (works in bulk and with quantities), move many assets to one location
- **Kits:** list, get, create (optionally with assets), add or remove assets, assign or release custody in bulk, change location
- **Bookings:** list, calendar, get, available assets, create, update, add or remove assets, reserve, check out, check in, cancel, archive, duplicate, delete, booking tags

Every tool takes an optional `orgId`. Tools that delete or cancel things are marked with `destructiveHint`.

Not covered yet: audits, partial check-in/check-out, model requests.

Kit creation and kit contents use Shelf's web forms instead of the mobile API, so a Shelf update may break them.

## Development

```sh
npm install
npm run dev     # tsc --watch
```

## License

MIT