Tdarr MCP

A FastMCP server that exposes the endpoints in tdarr.openapi.json as MCP tools. The document must be a valid OpenAPI 3.x specification; Swagger/OpenAPI 2.0 is not converted by this project.

Skill

A skill is provided which can be used to assist with investigating failed transcode jobs

npx skills add hollanbm/tdarr-mcp

Generate the OpenAPI specification

Generate tdarr.openapi.json repeatably from Tdarr's published Swagger 2 document:

make openapi TDARR_URL=https://tdarr.tld

The target pins swagger2openapi, enables its source repair mode, removes the invalid empty externalDocs object emitted from Tdarr's source, and verifies with uv tool run fastmcp inspect that FastMCP can load every generated tool before replacing the existing file. Override the source when needed:

make openapi TDARR_URL=https://your-tdarr.example.com
# Or provide the complete documentation URL:
make openapi TDARR_DOCS_URL=https://your-tdarr.example.com/api/v2/public/api-docs/json

Run

Python 3.11+ and uv are recommended:

export TDARR_URL=http://localhost:8265
# If API authentication is enabled in Tdarr:
export TDARR_API_KEY=your-api-key

uv run tdarr-mcp

The server uses Streamable HTTP and listens on http://0.0.0.0:8000/mcp by default. Example Codex MCP configuration:

[mcp_servers.tdarr]
url = "http://localhost:8000/mcp"

Configuration variables:

• MCP_HOST — HTTP bind address (default 0.0.0.0)
• MCP_PORT — HTTP port (default 8000)
• MCP_PATH — Streamable HTTP endpoint path (default /mcp)
• TDARR_URL — Tdarr server URL (default http://localhost:8265)
• TDARR_API_KEY — optional API key
• TDARR_API_KEY_HEADER — API-key header (default X-API-Key)
• TDARR_TIMEOUT — HTTP timeout in seconds (default 30)
• TDARR_OPENAPI_PATH — optional alternate specification path