astra-mcp

An MCP server for 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

npm install
npm run build

3. Register the server

Claude Code:

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:

{
  "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:

$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), 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

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
$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

# 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