# astra-mcp

An [MCP](https://modelcontextprotocol.io) server for [Astra](https://github.com/Boof2015/astra)'s
Companion API v2. It lets Claude and other MCP clients see and drive a running Astra desktop music
player — what's playing, search the library, start and queue music, manage favorites and playlists.

Read-only by default: Astra ships the API disabled, and each capability is a separate switch the
user controls. This server adapts to whatever is granted and hides the tools that aren't.

## Setup

### 1. Turn on Astra's Local API

In Astra: **Settings → Integrations → Local API**.

| Switch | Grants | Tools it unlocks |
| --- | --- | --- |
| Local Integration API | `observe` | `astra_now_playing`, `astra_queue`, `astra_capabilities` |
| External Playback Controls | `playback-control` | `astra_control`, `astra_play`, `astra_enqueue`, `astra_queue_edit` |
| Library Search | `library-search` | `astra_search`, `astra_open` |
| Favorites & Playlist Changes | `library-write` | `astra_set_favorite`, `astra_playlist` |

Copy the **Local API Key** from that panel. The token only works over `127.0.0.1`.

### 2. Build

```sh
npm install
npm run build
```

### 3. Register the server

Claude Code:

```sh
claude mcp add astra --env ASTRA_API_TOKEN=<your-token> -- node /absolute/path/to/astra-mcp/dist/index.js
```

Claude Desktop (`claude_desktop_config.json`) and other clients:

```json
{
  "mcpServers": {
    "astra": {
      "command": "node",
      "args": ["/absolute/path/to/astra-mcp/dist/index.js"],
      "env": { "ASTRA_API_TOKEN": "your-token" }
    }
  }
}
```

### 4. Browser-based clients (llama.cpp WebUI, and similar)

Clients that run in a browser cannot spawn a subprocess, so stdio is not an
option for them. Start the server in HTTP mode instead:

```powershell
$env:ASTRA_API_TOKEN = 'your-token'
node dist/index.js --http          # http://127.0.0.1:38500/mcp
node dist/index.js --http=9000     # or pick a port
```

Then in llama.cpp: launch `llama-server` with `--webui-mcp-proxy` (spelled
`--ui-mcp-proxy` on some builds) so the WebUI can reach it past CORS, and add
`http://127.0.0.1:38500/mcp` as an MCP server in the WebUI settings.

`GET /health` reports whether the Astra link is up and which scopes are granted
— the quickest way to tell a broken token from a stopped app.

The HTTP transport is **stateless**: it never issues an `Mcp-Session-Id`.
That is deliberate. llama.cpp's WebUI does not echo that header back
([ggml-org/llama.cpp#20471](https://github.com/ggml-org/llama.cpp/issues/20471)),
so a stateful server would reject every call after `initialize`. The trade-off
is that HTTP clients get no server-initiated messages: no `tools/list_changed`
when you flip a scope switch in Astra, and no resource-update notifications.
Tool calls are unaffected. Both work normally over stdio.

`GET /mcp` returns 405 for the same reason — there is no session to push a
stream to, and an open one would leak.

### Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `ASTRA_API_TOKEN` | — | Local API Key from Astra settings. Required. |
| `ASTRA_API_URL` | `http://127.0.0.1:38401` | Set this if you changed the port in Astra. |
| `ASTRA_POSITION_INTERVAL_MS` | `1000` | How often Astra pushes position updates (250–5000). |
| `ASTRA_DISABLE_EVENTS` | unset | Set to `1` to poll instead of holding an event stream. |
| `ASTRA_MCP_HTTP_PORT` | `38500` | Enables HTTP mode, same as `--http`. |
| `ASTRA_MCP_HTTP_HOST` | `127.0.0.1` | Bind address for HTTP mode. |
| `ASTRA_MCP_HTTP_ORIGINS` | empty | Comma-separated browser origins allowed to call the server directly. |

A missing token is a warning, not a crash — the server starts and each tool explains what to fix.

> **On `ASTRA_MCP_HTTP_ORIGINS`:** this process holds a token that can control
> your music player, so no browser origin is allowed by default. Any page you
> allowlist can drive Astra. You do not need this for llama.cpp — its proxy
> calls from the server side, where CORS does not apply.

## Tools

| Tool | What it does |
| --- | --- |
| `astra_search` | Find tracks, albums, artists, playlists. **Start here** — everything else takes refs from it. |
| `astra_now_playing` | Current track, position, volume, shuffle, repeat, output device. |
| `astra_control` | play, pause, stop, next, previous, seek, set-volume, set-muted, set-shuffle, set-repeat. |
| `astra_play` | Play a ref now, replacing the queue. |
| `astra_enqueue` | Add a ref to the queue, `next` or `end`. |
| `astra_open` | Focus the Astra window on a ref without playing it. |
| `astra_queue` | Read the queue with per-item ids. |
| `astra_queue_edit` | Move, remove, or clear upcoming queue items. |
| `astra_set_favorite` | Set a track's favorite state explicitly. |
| `astra_playlist` | Create, rename, and edit the contents of normal playlists. |
| `astra_capabilities` | Granted scopes, features, limits — the tool to reach for when something is 403. |

### Resources

`astra://playback`, `astra://queue`, and `astra://capabilities` are live JSON views that support
subscriptions. `astra://artwork/{ref}` returns album art as a blob — a resource rather than a tool
so a model can't flood its own context with 2 MiB images.

## How it works

**Refs are opaque.** Astra never exposes file paths or database ids; it hands out signed
`AstraRef` strings. Nothing here accepts a name, so every flow is search → act. Refs can go stale
and start returning 404, which means search again.

**One event stream, not polling.** The server holds a single SSE connection to `/v2/events` and
keeps playback and queue snapshots warm, so `astra_now_playing` usually costs zero HTTP requests.
Astra's budget is 120 requests/minute shared across everything using the token; a client-side
limiter keeps this server under it by queuing rather than failing. If the stream drops, tools fall
back to direct reads.

**202 is not "done".** Playback, intent, and queue commands are queued to Astra's renderer and
return immediately. `astra_control` and `astra_play` wait briefly on the event stream and report the
state Astra actually reached, rather than claiming success.

**The tool list is live.** Flipping a switch in Astra's settings force-closes the event stream; the
reconnect handshake carries the new scopes, and the server enables or disables tools to match.
(Over HTTP the gating still applies, but the client is not notified — it sees the change on its next
`tools/list`.)

**One Astra connection, many MCP servers.** HTTP mode builds a fresh `McpServer` per request, as
stateless mode requires, but they all share a single `AstraRuntime` holding one HTTP client and one
event stream. Otherwise each request would open its own stream and exhaust Astra's limit of eight.

## What this cannot do

Astra's v2 contract deliberately omits catalog browsing, audio streaming, metadata editing, library
scans, remote-source administration, settings, DSP/EQ, lyrics, playlist deletion, and dynamic
playlist rules. Those endpoints do not exist, so no tool here can reach them. Library writes are
limited to favorites and locally owned normal playlists — mirrored (Jellyfin/Subsonic) and dynamic
playlists reject edits.

Only the loopback transport is supported. Astra also serves the same v2 surface to paired LAN
devices over HTTPS on port 38402, which needs its own pairing flow.

## Development

```sh
npm run build       # tsc
npm test            # build, then unit + contract tests
npm run inspector   # MCP Inspector against the built server
npm run smoke       # end-to-end against a running Astra (read-only)
```

Smoke testing runs against a live Astra and is read-only unless you opt in.
`--play` replaces the current queue; `--write` creates a playlist you then have
to delete by hand, since Astra has no delete endpoint. Neither touches existing
playlists or favorites.

```powershell
# PowerShell
$env:ASTRA_API_TOKEN = 'your-token'
npm run smoke
node scripts/smoke.mjs "Miles Davis"           # + search
node scripts/smoke.mjs "Miles Davis" --play    # + play and enqueue
node scripts/smoke.mjs "Miles Davis" --write   # + playlist creation
```

```sh
# bash / zsh
export ASTRA_API_TOKEN='your-token'
npm run smoke
```

`src/types.ts` mirrors Astra's `src/types/companionApi.ts` by hand, and `ASTRA_ENDPOINTS` in
`src/client.ts` lists every endpoint this server calls. `test/contract.test.mjs` checks both against
Astra's own `docs/api/openapi-v2.json`, and fails if the source calls a path that isn't declared.
It looks for the Astra checkout as a sibling directory; set `ASTRA_REPO` if yours lives elsewhere.

## License

GPL-3.0