OpenClaw + Jellyfin: Control Your Media Server From Chat

What You Can Actually Do

Once the connection is live, these all become plain-language requests from whatever channel your agent runs on:

• Search the library — “do we have anything by Studio Ghibli?”
• Start playback — “put the next unwatched episode on the living room TV”
• Check sessions — “is anyone streaming right now, and what?”
• Trigger maintenance — “scan the library, I just added files”
• Query recent additions — “what got added this week?”
• Manage users — account and access administration, if you allow it

The useful part is not any single command — it is that you do not have to open the web UI on a laptop to do them. Combined with scheduled jobs, the agent can also report on its own: a weekly message listing what was added, or an alert when a scan fails.

Step 1: Create a Jellyfin API Key

In the Jellyfin web UI, open Dashboard → Advanced → API Keys and create a new key, naming it something you will recognise later (for example openclaw-agent). Copy the value immediately — Jellyfin shows it once.

Note the server URL as well, in the form http://192.168.1.50:8096 for a LAN install or your HTTPS domain if you have one published.

Step 2: Choose an MCP Server

Several community Jellyfin MCP servers exist, ranging from thin REST wrappers to larger agent frameworks. They differ in scope, but nearly all follow the same configuration convention:

JELLYFIN_BASE_URL=http://192.168.1.50:8096
JELLYFIN_TOKEN=your-api-key-here

Some also accept JELLYFIN_USERNAME and JELLYFIN_PASSWORD in place of a token. Prefer the API key: it is revocable from the dashboard without changing your account password, and it is the credential you want to hand to software.

Pick one that exposes only the operations you want. A server that can delete media is a server your agent can be talked into using — a read-and-playback scope is the sane default for a media library.

Step 3: Register It With OpenClaw

Add the MCP server to your openclaw.json. The exact command depends on the implementation you chose; the shape is consistent:

{
  "mcpServers": {
    "jellyfin": {
      "command": "npx",
      "args": ["-y", "<jellyfin-mcp-package>"],
      "env": {
        "JELLYFIN_BASE_URL": "http://192.168.1.50:8096",
        "JELLYFIN_TOKEN": "your-api-key-here"
      }
    }
  }
}

Restart the gateway, and the Jellyfin tools appear in the agent's tool list. The general mechanics — where the config lives, how tools are discovered, how to debug a server that will not start — are covered in the OpenClaw MCP guide.

Networking: The Part That Trips People Up

A Jellyfin server on your home LAN is not reachable from a hosted agent container. If you are running OpenClaw Launch rather than self-hosting, you have three honest options:

• Tailscale — put the agent and the media server on the same tailnet. This is the cleanest answer and needs no ports opened. See the Tailscale guide.
• Publish Jellyfin over HTTPS — a reverse proxy with a real certificate and authentication in front. More exposure, more to maintain.
• Self-host the agent beside it — run OpenClaw on the same machine or LAN, where 127.0.0.1:8096 just works.

What you should not do is forward port 8096 to the internet with an API key as the only thing between strangers and your server.

Keep the Blast Radius Small

An agent with a Jellyfin admin key can do everything an admin can, including things you never meant to authorise. Two habits make this safe:

• Use a dedicated key with a recognisable name so you can revoke exactly this integration without touching anything else
• Prefer an MCP server whose exposed tools stop at search, playback and status, rather than one that also deletes media and users

This is the general principle for connecting home infrastructure to an agent — the same reasoning as in our agent security guide.

Troubleshooting

401 Unauthorized

The key is wrong, was regenerated, or is being sent in the wrong header. Confirm it works outside the agent first: curl -H "X-Emby-Token: KEY" http://server:8096/System/Info.

The agent says it has no Jellyfin tools

The MCP server did not start. Check the gateway logs for the launch error — a missing package or a bad env var shows up there, not in the chat.

Playback commands do nothing

Jellyfin can only control a client that is actively connected and reports itself as remote-controllable. If no session is registered for that device, there is nothing to send the command to — open the app on the target device first.

What's Next?

• OpenClaw MCP guide — how MCP servers are configured and debugged
• Connect Home Assistant — the same pattern for home automation
• OpenClaw + Tailscale — reach home services from a hosted agent
• Scheduled jobs — weekly library reports without asking
• Home automation use case