mcp-jellyfin/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install dependencies
uv sync

# Run the MCP server
python src/jellyfin_mcp/server.py

# Run tests
pytest

# Run a single test
pytest tests/test_server.py::test_search_items_tool

Architecture

This is a Python MCP server that wraps the Jellyfin media server REST API using the FastMCP framework.

Two-layer design:

• src/jellyfin_mcp/client.py — JellyfinClient: low-level async HTTP client using httpx. Handles auth via MediaBrowser Token header, constructs URLs, and maps Jellyfin API responses to Python types.
• src/jellyfin_mcp/server.py — MCP tool definitions via @mcp.tool() decorators. Each tool calls JellyfinClient methods and formats results as plain strings for AI consumption. The client instance is a module-level singleton initialized at import time from env vars.

Configuration: JELLYFIN_URL and JELLYFIN_API_KEY must be set (via .env file or environment). The server raises ValueError at startup if either is missing.

Testing: Tests mock jellyfin_mcp.server.client at the module level and patch individual JellyfinClient methods with AsyncMock. The mock_env fixture is autouse=True so env vars are always set during tests.