tdarr-mcp

A Model Context Protocol (MCP) server for Tdarr — the distributed media transcoding/health-check automation platform. It gives AI assistants (Claude Desktop, Claude Code, and any MCP-compatible client) programmatic control over a Tdarr server through its HTTP API.

Speaks MCP over stdio and exposes 105 tools across 12 categories.

Features

Category	Tools	Examples
Libraries	19	scan, create/update/delete libraries, folder & filter settings, transcode/health-check options
Nodes	19	list nodes & workers, pause/resume, set worker limits, reassign jobs
Server	18	server status, settings, schedules, statistics, maintenance
Files	11	search, bulk update/delete, create samples, inspect file records
Plugins	9	list/get plugins, plugin stacks, community plugins
Stats	7	transcode/health stats, space saved, processing history
Users	7	list/create/update/delete users, auth settings
Backups	5	create backup, status, reset
Jobs	5	queue management, job control
Database	3	cruddb, search DB, client queries
Automations	1	run an automation
Processes	1	process info

All tools are prefixed tdarr_* (e.g. tdarr_get_nodes, tdarr_search_db, tdarr_run_automation).

Prerequisites

• Node.js ≥ 18 (uses the native fetch API), or Bun.
• A running Tdarr server reachable over HTTP.

Installation & build

git clone https://github.com/maximeallanic/tdarr-mcp.git
cd tdarr-mcp

# with Bun
bun install
bun run build      # tsc → dist/

# …or with npm
npm install
npm run build

This compiles src/ to dist/.

Configuration

The server reads its target from environment variables:

Variable	Required	Description
TDARR_URL	❌	Base URL of the Tdarr server. Defaults to http://localhost:8265.
TDARR_API_KEY	❌	API key, sent as the x-api-key header. Only needed if your Tdarr instance has API auth enabled.

Usage with an MCP client

Add the server to your MCP client configuration (e.g. Claude Desktop / Claude Code mcpServers block):

{
  "mcpServers": {
    "tdarr": {
      "command": "node",
      "args": ["/absolute/path/to/tdarr-mcp/dist/main.js"],
      "env": {
        "TDARR_URL": "http://your-tdarr-host:8265"
      }
    }
  }
}

During development you can run the TypeScript entry directly with Bun (no build step):

TDARR_URL=http://your-tdarr-host:8265 bun run src/main.ts

How it works

Each tool is a thin declarative mapping (TdarrToolDef) to a Tdarr API endpoint: HTTP method, path (with :param substitution), and an input JSON schema. POST bodies are wrapped in { data: ... } by default (Tdarr's convention) unless a tool sets dataWrapped: false. Responses are returned as pretty-printed JSON text.

License

MIT © Maxime Allanic