Deadline MCP Server

AI access to a Thinkbox Deadline 10 render farm via its Web Service REST API, exposed as Model Context Protocol tools. Works with Hermes, Claude, and any MCP-compatible client.

• 18 tools — 9 read + 9 write (see Tools)
• Self-contained — own venv, no host dependencies beyond Python 3.10+
• Env-configured — no secrets in the repo

---

Requirements

Requirement	Detail
Python	3.10+
Deadline Web Service	deadlinewebservice running, default port 8081
Network	The target machine must reach the Web Service (same host, LAN, or tailnet)
Credentials	A Deadline user account (username + password — not email)

---

Install

git clone https://github.com/officefiction/deadline-mcp-server.git
cd deadline-mcp-server
./install.sh

install.sh creates a venv/, installs mcp + httpx, and self-tests the tool registry. Expected output ends with:

tools (18): deadline_complete_job, deadline_delete_job, ...

Version pin: the server targets the MCP 1.x Python SDK (mcp>=1.28,<2). MCP 2.x moved FastMCP — do not upgrade past 2.x without testing.

---

Configure

cp .env.example .env
# edit .env:
#   DEADLINE_WS_URL=http://localhost:8081   (or your host)
#   DEADLINE_WS_USER=<deadline username>
#   DEADLINE_WS_PASS=<deadline password>
chmod 600 .env

Variable	Required	Default	Description
DEADLINE_WS_URL	no	http://localhost:8081	Base URL of the Deadline Web Service
DEADLINE_WS_USER	yes	—	Deadline user account (not email)
DEADLINE_WS_PASS	yes	—	Deadline account password
DEADLINE_MCP_READONLY	no	false	true = read-only tools only (no job mutations)

---

Register in Hermes

Add this block to ~/.hermes/config.yaml (path must match where you cloned):

mcp_servers:
  deadline:
    command: "/opt/deadline-mcp-server/venv/bin/python"
    args: ["/opt/deadline-mcp-server/server.py"]
    env:
      DEADLINE_WS_URL: "${DEADLINE_WS_URL}"
      DEADLINE_WS_USER: "${DEADLINE_WS_USER}"
      DEADLINE_WS_PASS: "${DEADLINE_WS_PASS}"
    enabled: true
    timeout: 120
    connect_timeout: 60

Then put the three DEADLINE_WS_* values in the profile's .env (chmod 600), restart the gateway, and verify:

hermes mcp test deadline   # expect 18 tools discovered

Register in other MCP clients

Point any MCP client at the stdio server:

{
  "command": "/opt/deadline-mcp-server/venv/bin/python",
  "args": ["/opt/deadline-mcp-server/server.py"],
  "env": {
    "DEADLINE_WS_URL": "http://localhost:8081",
    "DEADLINE_WS_USER": "...",
    "DEADLINE_WS_PASS": "..."
  }
}

---

Tools

Read (always available)

Tool	Description
deadline_farm_status	Overall farm snapshot: workers, jobs by state, groups, pools
deadline_list_jobs	List jobs, filter by state / user
deadline_get_job	One job by ID
deadline_job_tasks	Tasks (chunks) of a job, per-task status
deadline_job_reports	Job reports / render logs
deadline_list_workers	Farm workers (slaves) with status + heartbeat
deadline_list_users	Repository users
deadline_list_groups	Worker groups
deadline_list_pools	Job pools

Write (disabled with DEADLINE_MCP_READONLY=true)

Tool	Description
deadline_suspend_job	Stop new tasks from starting
deadline_resume_job	Resume a suspended job
deadline_requeue_job	Re-run a job's tasks
deadline_complete_job	Mark a job completed
deadline_fail_job	Mark a job failed
deadline_pend_job	Hold a job until released
deadline_release_pending_job	Release a pended job to the queue
deadline_set_job_priority	Change a job's priority
deadline_delete_job	Delete a job

Job states

State	Meaning
0	Unknown
1	Active
2	Suspended
3	Completed
4	Failed
5	Deleted
6	Pending

---

Architecture

MCP client (Hermes / Claude / ...)
        │  stdio (JSON-RPC)
        ▼
server.py  (FastMCP, mcp<2)
        │  HTTP Basic auth
        ▼
Deadline Web Service  (deadlinewebservice, :8081)
        │  REST
        ▼
Deadline repository  (render farm)

Key API facts (this server handles them automatically):

• Workers are served under /api/slaves (not /api/workers)
• Job state lives in the top-level Stat field
• Auth is a Deadline user account — the Web Service returns 401 without it

---

Development

# Regenerate/refresh docs against the live tool registry
python3 scripts/deadline_mcp_docs.py --outline   # (internal tooling, not in this repo)

---

License

Internal tooling for the Office Fiction project. MIT.