Cinephage MCP Server

This repository contains the Model Context Protocol (MCP) server for Cinephage. It acts as a bridge between AI agents (like Claude or opencode) and your local Cinephage instance.

💡 Explanation: How It Works

This server operates by dynamically parsing the cinephage.openapi.yaml specification file. Instead of hardcoding individual tools, it iterates through all 350+ API endpoints defined in the spec and registers each one as an independent MCP tool. It automatically maps OpenAPI parameters (path, query, and JSON bodies) into strict Zod schemas, ensuring the AI agent receives perfect type validation before executing a request.

The Concept of Roles

Exposing 350+ tools simultaneously can overwhelm an AI agent's context window. To solve this, the server utilizes Roles. By passing a --role flag upon startup, you can filter which tools the server exposes based on OpenAPI tags:

• Core Role (--role=core): Exposes ~140 tools related to daily media operations (Library, Search, Queue, Subtitles, Activity). This is recommended for daily use.
• Admin Role (--role=admin): Exposes ~210 tools related to infrastructure and configuration (Indexers, Download Clients, Settings, System Health). This should only be enabled when explicitly performing system maintenance.

📚 Tutorials

Development Setup

This section is only needed if you want to run the server from source (e.g. for contributing). If you just want to use the server, skip to How to Configure in opencode or Claude Desktop, which uses npx and requires no local setup.

To run the MCP server from source, you must first build the TypeScript project and provide your Cinephage credentials.

1. Install Dependencies

   npm install

2. Build the Project The server is written in TypeScript and must be compiled to standard JavaScript before execution.

   npm run build

3. Configure Environment Variables The server expects a .env file two directories above the src folder (at the workspace root). Ensure your .env contains:

   CINEPHAGE_URL=http://your-cinephage-ip:3030
   CINEPHAGE_API_KEY=your_api_key_here

🎯 How-To Guides

How to Configure in opencode or Claude Desktop

The easiest way to use the server is via npx, which pulls the latest version straight from the public npm registry — no GitHub token or custom registry configuration required. We highly recommend splitting the configuration into two separate servers so you can keep the admin tools disabled by default.

Add the following to your opencode.json (or claude_desktop_config.json):

{
  "mcp": {
    "cinephage-core": {
      "type": "local",
      "command": ["npx", "-y", "@coldfox-pb/cinephage-mcp", "--role=core"],
      "enabled": true,
      "env": {
        "CINEPHAGE_URL": "http://your-cinephage-ip:3030",
        "CINEPHAGE_API_KEY": "your_api_key_here"
      }
    },
    "cinephage-admin": {
      "type": "local",
      "command": ["npx", "-y", "@coldfox-pb/cinephage-mcp", "--role=admin"],
      "enabled": false,
      "env": {
        "CINEPHAGE_URL": "http://your-cinephage-ip:3030",
        "CINEPHAGE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: Change enabled: false to true for the admin server when you need the AI to debug or reconfigure your Cinephage settings.

📖 Reference

CLI Arguments

The compiled server (dist/index.js) accepts the following arguments:

| Argument | Description | | :--- | :--- | | --role=core | Loads only media-focused endpoints (e.g., tags: Library, Movies, Search). | | --role=admin | Loads only configuration/system endpoints (e.g., tags: Settings, Indexers). | | --role=all | (Default if omitted). Loads all 350+ endpoints simultaneously. |

Environment Variables

The server requires configuration to communicate with your Cinephage instance. It attempts to load these from a .env file.

| Variable | Required | Default | Description | | :--- | :--- | :--- | :--- | | CINEPHAGE_URL | No | http://your-cinephage-ip:3030 | The base URL of your Cinephage instance. | | CINEPHAGE_API_KEY | Yes | "" | The API key used to authenticate requests. |