How to Configure and Use the FastMCP Server for Programmatic Access in Music Assistant

The FastMCP server is a built-in provider plugin that exposes Music Assistant's core functionality via a JSON-RPC-style ASGI endpoint, enabling external scripts to control playback and query player states using the fastmcp client library or direct HTTP requests.

The FastMCP server eliminates the need for browser-based interaction by providing programmatic access to the music-assistant/server repository's media control API. When enabled, this provider creates a lightweight, high-performance endpoint that registers tools such as find_and_play and get_player_state, allowing automation frameworks and custom scripts to manage your audio ecosystem remotely.

What Is the FastMCP Server?

The FastMCP server is implemented as a provider plugin (fastmcp_server) within the Music Assistant architecture. When activated, it instantiates the MCPServerRuntime class, which constructs an ASGI application (http_app) that listens on a configurable TCP port. This runtime registers a suite of tools that mirror the public Python API, exposing methods to control players, adjust volume, and search the media library.

Unlike the standard web interface, this endpoint is designed specifically for machine-to-machine communication, utilizing a lightweight protocol that supports both authenticated and open-access modes depending on your security requirements.

Configuration Options

The server is configured through the mcp section in your config.yaml or via the Home Assistant UI configuration panel. All parameters are defined in the provider initialization and runtime setup.

mcp:
  enabled: true          # Toggle the server on/off

  host: "0.0.0.0"        # Interface to bind (default: 0.0.0.0)

  port: 8096             # TCP port for incoming connections

  token: "your-secret-jwt-token"  # Optional: enables JWT authentication

When a token is specified, the server validates the Authorization: Bearer <token> header on every request using the logic in music_assistant/helpers/jwt_auth.py. If omitted, the endpoint runs without authentication, suitable only for trusted network environments.

Core Architecture and Source Files

The implementation spans four critical files in the repository:

• music_assistant/providers/fastmcp_server/provider.py: Contains the MCPServerProvider class that integrates the runtime into the Music Assistant core, handling lifecycle events like start() and setup_runtime().
• music_assistant/providers/fastmcp_server/server.py: Implements MCPServerRuntime, creates the ASGI application, and registers available tools that wrap the core API methods.
• music_assistant/providers/fastmcp_server/manifest.json: Declares the MCP resource type (resource_name: "Music Assistant MCP") for the plugin registry, allowing the core loader to discover and initialize the provider.
• music_assistant/helpers/jwt_auth.py: Provides JWT token validation when authentication is enabled, ensuring secure programmatic access.

Enabling the FastMCP Server

To activate the server, modify your Music Assistant configuration to enable the MCP provider and specify your preferred network settings:

# config.yaml

mcp:
  enabled: true
  host: "0.0.0.0"
  port: 8096
  token: "super-secret-jwt-token-123"

Upon restart, the MCPServerProvider initializes the runtime, mounts the ASGI app, and begins listening for incoming FastMCP protocol connections on the specified port.

Connecting Programmatically

Once running, you can interact with the server using either the official fastmcp client library or direct HTTP requests.

Using the FastMCP Client Library

The Python fastmcp library provides the most straightforward integration, handling serialization and connection management automatically:

from fastmcp import FastMCP, Client

# Initialize the client connection

mcp = FastMCP(
    name="music_assistant",
    host="127.0.0.1",
    port=8096,
    token="super-secret-jwt-token-123"
)

client = Client(mcp)

# Search and play a track

await client.call_tool(
    "find_and_play",
    {
        "search_query": "Imagine Dragons",
        "player_id": "living_room_sonos"
    }
)

# Query current player state

state = await client.call_tool(
    "get_player_state",
    {"player_id": "living_room_sonos"}
)
print(state)

Direct HTTP API Calls

For languages or environments without the fastmcp library, you can invoke tools directly via HTTP POST requests to the /call_tool endpoint:

curl -X POST "http://127.0.0.1:8096/call_tool" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer super-secret-jwt-token-123" \
     -d '{
           "tool": "set_player_volume",
           "params": {
             "player_id": "living_room_sonos",
             "volume_level": 75
           }
         }'

Starting the Server Programmatically

For advanced use cases, such as testing or custom plugin development, you can instantiate and start the server manually from within Python:

from music_assistant.providers.fastmcp_server.provider import MCPServerProvider

# Assuming 'core' is your Music Assistant core instance

mcp_provider = MCPServerProvider.__new__(MCPServerProvider)
mcp_provider.core = core
mcp_provider._setup_runtime()  # Creates the MCPServerRuntime instance

await mcp_provider.start()     # Starts the ASGI server and begins accepting connections

Summary

• The FastMCP server is a provider plugin in music-assistant/server that creates an ASGI endpoint for remote control.
• Configuration occurs via the mcp section in config.yaml, supporting custom ports, hosts, and optional JWT authentication.
• Core implementation files include provider.py (lifecycle management), server.py (ASGI runtime), and jwt_auth.py (security).
• Access the server using the fastmcp client library or direct HTTP POST calls to /call_tool.
• Available tools mirror the public API, including find_and_play, get_player, and set_player_volume.

Frequently Asked Questions

What is the default port for the FastMCP server?

The FastMCP server defaults to port 8096 when enabled. You can override this by setting the port value in the mcp configuration section of your config.yaml.

Is authentication required to use the FastMCP server?

Authentication is optional. If you omit the token parameter in the configuration, the server runs in open-access mode. When a token is provided, every request must include an Authorization: Bearer <token> header, validated against the logic in music_assistant/helpers/jwt_auth.py.

What tools are available through the FastMCP server?

The server exposes tools that mirror the Music Assistant public API, including find_and_play for media search and playback, get_player and get_player_state for querying device status, and set_player_volume for audio control. The full list is registered dynamically in MCPServerRuntime within music_assistant/providers/fastmcp_server/server.py.

Can I run the FastMCP server without the Music Assistant web interface?

Yes. The FastMCP server operates independently as a background provider within the Music Assistant core. It does not require the web interface to be running, making it suitable for headless installations where you only need programmatic access via the ASGI endpoint.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}