mcp-vods

This MCP server (mcp-vods) is designed to power a Binge-watch style experience by providing AI-assisted search and playback addresses for movies and TV shows. It integrates with LunaTV/MoonTV sources when configured, and can push playback to compatible devices such as Xiaomi TVs using the MITV configuration. The server exposes its API through the MCP framework and can be started either via uvx (Python-based) or other supported deployment methods as shown in the installation options. After startup, you can use the provided search and playback features to locate streamable sources and direct them to your TV clients.

Prerequisites:

• You have a supported MCP runtime available (uvx for Python-based deployment, or Docker, etc.).
• Access to configure environment variables for your deployment target.

Option A: Install with uvx (recommended for quick start)

1. Ensure uvx is installed on your system.
2. Create or update your MCP configuration file (e.g., mcp-config.json) with the following content:

{
  "mcpServers": {
    "vods": {
      "command": "uvx",
      "args": ["mcp-vods"],
      "env": {
        "MITV_LIST_CFG": "客厅电视:192.168.1.11"
      }
    }
  }
}

3. Run the MCP loader or your MCP manager to pick up the configuration.

Option B: Install with Docker

1. Create a directory for the server and pull the docker-compose configuration:

mkdir /opt/mcp-vods
cd /opt/mcp-vods
wget https://raw.githubusercontent.com/aahl/mcp-vods/refs/heads/main/docker-compose.yml

2. Start the container:

docker-compose up -d

3. If using the Docker approach, the server’s exposed MCP endpoint can be accessed at the default Streamable HTTP URL provided in the README (e.g., http://0.0.0.0:8821/mcp).

Option C: Other deployment methods Refer to the README’s Home Assistant OS add-on and other integration options for environments outside uvx or Docker. The environment-variable approach remains consistent across methods.

Tips and common considerations:

• If you plan to cast to 小米电视, ensure you configure MITV_LIST_CFG or MITV_LOCAL_IP to enable local-network playback; otherwise, playback may fail to start on TVs.
• Optional environment variables for source integration include VOD_CONFIG_URL, SEARCH_CACHE_TTL, and MAX_SEARCH_SITES to customize how and where content data is fetched and how long search results are cached.
• For LunaTV/MoonTV integration, you can set MOON_BASE_URL and LUNA_BASE_URL along with LUNA_USERNAME and LUNA_PASSWORD to enable subscription-based or remote content access.
• The REST/export URL mentioned in the README (Streamable HTTP) is typically exposed when using Docker and a specific port mapping; verify your deployment’s port mappings to reach the MCP API.
• If you run into issues with multiple TVs, MITV_LIST_CFG should list all devices in the format Station:IP; another common pattern is to provide a single MITV_LOCAL_IP per device setup.
• The provided CLI command to add the server to Claude Code or other assistants demonstrates interoperability; you can adapt similar commands for your tooling.