> For the complete documentation index, see [llms.txt](https://docs.nuclearplayer.com/nuclear/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuclearplayer.com/nuclear/integrations/mcp-server.md).

# MCP Server

Nuclear includes a built-in [MCP](https://modelcontextprotocol.io/) server that lets your AI control the music player, doing pretty much anything that you can!

## Enable the server

1. Open Nuclear → Settings → Integrations.
2. Toggle `Enable MCP Server` on.
3. The server starts on `http://127.0.0.1:8800/mcp` (localhost only). If port 8800 is taken, it tries 8801, 8802, and so on up to 8809.
4. The **MCP Server URL** field below the toggle shows the actual URL. Click the copy button to grab it.

## Connect your AI tool

The server URL is `http://127.0.0.1:8800/mcp` using the `Streamable HTTP` transport.

{% tabs %}
{% tab title="Claude Code" %}

```bash
claude mcp add nuclear --transport http http://127.0.0.1:8800/mcp
```

{% endtab %}

{% tab title="OpenCode" %}
Add to your `opencode.json`:

```json
{
  "mcp": {
    "nuclear": {
      "type": "remote",
      "url": "http://127.0.0.1:8800/mcp"
    }
  }
}
```

{% endtab %}

{% tab title="Codex CLI" %}
Add to `~/.codex/config.toml`:

```toml
[mcp_servers.nuclear]
url = "http://127.0.0.1:8800/mcp"
```

Or via the CLI:

```bash
codex mcp add nuclear --url http://127.0.0.1:8800/mcp
```

{% endtab %}

{% tab title="Claude Desktop / Cursor / Windsurf" %}
Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):

```json
{
  "mcpServers": {
    "nuclear": {
      "url": "http://127.0.0.1:8800/mcp"
    }
  }
}
```

{% endtab %}

{% tab title="MCP Inspector" %}

```bash
npx @modelcontextprotocol/inspector
```

Enter `http://127.0.0.1:8800/mcp` as the URL and select `Streamable HTTP` as the transport.
{% endtab %}
{% endtabs %}

## Tools

Nuclear exposes four MCP tools. The server uses a hierarchical discovery pattern: start broad, drill down, then act.

### `list_methods`

Lists available methods in a domain.

| Parameter | Type   | Required | Description                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `domain`  | string | yes      | One of: `Queue`, `Playback`, `Metadata`, `Favorites`, `Playlists`, `Dashboard`, `Providers`. |

Returns the method names and short descriptions for that domain.

### `method_details`

Gets full details for a single method: its description, parameter names and types, and return type.

| Parameter | Type   | Required | Description                                                         |
| --------- | ------ | -------- | ------------------------------------------------------------------- |
| `method`  | string | yes      | The method name in `Domain.method` format, e.g. `Queue.addToQueue`. |

### `describe_type`

Gets the JSON shape of a data type. Use this when `method_details` returns a parameter or return type that references a complex type.

| Parameter | Type   | Required | Description                                           |
| --------- | ------ | -------- | ----------------------------------------------------- |
| `type`    | string | yes      | The type name, e.g. `Track`, `QueueItem`, `Playlist`. |

### `call`

Calls a Nuclear API method.

| Parameter | Type   | Required | Description                                                                                                         |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `method`  | string | yes      | The method name in `Domain.method` format, e.g. `Queue.addToQueue`.                                                 |
| `params`  | object | no       | A JSON object with named fields matching the method's parameters. Omit or pass `{}` for methods with no parameters. |

## Discovery workflow

An agent follows this sequence to find and call an API method:

1. Read the `list_methods` tool description to see the seven available domains.
2. Call `list_methods` with a domain (e.g. `Queue`) to see that domain's methods.
3. Call `method_details` (e.g. `Queue.addToQueue`) to get parameter names, types, and the return type.
4. If a parameter or return type is a complex type like `Track`, call `describe_type` to see its fields.
5. Call `call` with the method name and parameters to execute it.

Each step returns a small, focused payload to save on tokens.

## Agent skill

If your AI tool supports skills (like Claude Code), you can install one that teaches the agent how to use Nuclear's MCP tools, including the discovery workflow, common recipes, and the full API reference.

[Download nuclear-mcp.zip](https://github.com/nukeop/nuclear/blob/master/packages/docs/.gitbook/assets/nuclear-mcp.zip)

Unzip it into your skills directory (e.g. `~/.claude/skills/`) and the agent will pick it up automatically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nuclearplayer.com/nuclear/integrations/mcp-server.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.