MCP Media Player

MCP Media Player connects your Home Assistant media player to the Cursor coding environment, letting you automate playback while your agent works. You can control play and pause from MCP tools, and set up Cursor rules to trigger actions automatically. This empowers you to manage media without manual intervention and keeps you focused on the task at hand.

How to use

You will run an MCP server for your media player and expose play and pause controls as MCP tools. Use an MCP client to invoke these actions from your automation rules or prompts. Create rules that start playback when you want to watch something and pause playback when you want to focus, then resume as needed. The server listens for commands and translates them into Home Assistant media player API calls.

How to install

Prerequisites you need before installing: Node.js 18 or higher, a running Home Assistant instance, and a valid Home Assistant long-lived access token.

Step by step commands to set up the MCP server:

# 1. Clone the repository
# Replace <repository-url> with the actual repository URL
git clone <repository-url>

# 2. Install dependencies
cd mcp-media-player
npm install

# 3. Configure MCP integration
# Copy the example config to your MCP config location and fill in real values
# Then edit the file to include your Home Assistant details

Configure the MCP integration by creating a JSON configuration that defines the local MCP server. The example below shows how to point MCP to your local script and supply the necessary Home Assistant details.

{
  "mcpServers": {
    "MediaPlayer": {
      "command": "node",
      "args": [
        "/absolute/path/to/your/media-player-mcp.js"
      ],
      "env": {
        "HA_URL": "http://your-ha-url:8123",
        "HA_TOKEN": "your_home_assistant_long_lived_token",
        "ENTITY_ID": "media_player.your_media_player_entity"
      }
    }
  }
}

Add Cursor rules to automate playback during the agent’s work. Copy the provided rules into your Cursor rules configuration so that play and pause are invoked at the right times.

Step 4 assumes you will start the MCP server next. You can run it locally or let your MCP client launch it automatically.

npm start

Additional setup notes

The example configuration uses a stdio-based MCP server that runs a Node script. Ensure the absolute path to your script is correct and that Home Assistant is reachable from the machine running the MCP server.

Security and notes

Keep your Home Assistant token secure. Store it in the environment and restrict access to the MCP server configuration. Use a strong, unique token and rotate it periodically as part of your security best practices.

Troubleshooting tips

If playback commands do not affect the media player, verify that the HA URL and token are correct, that the entity_id matches your Home Assistant integration, and that the MCP server process has the necessary permissions to run the Node script.

Available tools

play

Start playback on the configured Home Assistant media player via MCP tooling.

pause

Pause playback on the configured Home Assistant media player via MCP tooling.