content-mcp — Content MCP server

The official MCP server for the Content engine: give Claude, an IDE or any MCP-compatible agent the ability to drive your Content instance — analyze a URL, generate video/audio/subtitles/transcripts, watch the job, land the files in your library. It is an agentic facade over the official Python SDK: no REST of its own, no business logic.

any MCP client → content-mcp (this) → content_sdk → your Content engine (/api/v1)

Where downloaded files land

download_artifact writes to the machine running this server — the counterpart to delivery, which writes to the engine's library. One variable bounds it:

The refusal is deliberate. An MCP server writes to a real filesystem on an agent's say-so, so widening that is the operator's decision, taken once, rather than something a prompt can talk it into.

Install

The server is an ordinary Python application — nothing to clone:

uv tool install content-mcp     # isolated, on your PATH — recommended
content-mcp --help

# or
pipx install content-mcp

content-mcp on PyPI pulls content-sdk as an ordinary dependency, pinned to the matching release. The wheels are also attached to each GitHub release for air-gapped installs (uv tool install ./content_mcp-<v>-py3-none-any.whl --find-links .).

Connect it to your engine

One environment variable: CONTENT_API_URL (default http://localhost:8010). The server speaks stdio — your MCP client spawns it; you never run it by hand.

Claude Code

claude mcp add content --env CONTENT_API_URL=http://localhost:8010 -- content-mcp

Claude Desktop, Cursor, and other clients

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and any other client using the standard JSON shape:

{
  "mcpServers": {
    "content": {
      "command": "content-mcp",
      "env": { "CONTENT_API_URL": "http://localhost:8010" }
    }
  }
}

Then ask for something like "analyze this YouTube URL and download the audio into my library" — the expected flow is get_config → analyze_source → generate → get_job, ending with a delivered_path you can find under the engine's delivery folder.

Logs go to stderr (stdout carries only the MCP JSON-RPC framing), so a client's log pane shows them without corrupting the session.

Tools (intention-level, not one-per-endpoint)

Resources (read-only, content:// namespace)

content://analyses/{id}, content://jobs/{id}, content://artifacts/{id} — JSON views for a host to attach as context. Prompts are intentionally not provided yet.

For development

From a clone:

make install    # editable installs of the engine, SDK, CLI and MCP in one venv
claude mcp add content --env CONTENT_API_URL=http://localhost:8010 \
  -- apps/backend/.venv/bin/python -m content_mcp.server

Build the distributions with make wheels (they land in dist/).

Verification status

• Service logic over a mock transport: verified (tests/test_service.py).
• The MCP wiring against the real mcp library (tools, resource templates): verified (tests/test_server.py).
• The full journey — MCP service → SDK → real FastAPI engine → executor → delivery library, including delivery intent and mode: "none": verified in-process (tests/test_end_to_end.py, in make validate).
• The installed wheel driven over stdio by an MCP client session against a running engine: verified at packaging time (see the repository's release notes); re-run it after any transport change.

Design

• service.py — the intention logic; takes an SDK client, returns JSON. No MCP imports, no HTTP. Fully unit-tested over a mock transport.
• server.py — thin wiring: registers the tools/resources on an MCPServer and runs stdio. content-mcp → content_mcp.server:main.
• The layering is enforced by tests: the MCP server may import content_sdk only — never an HTTP client, never backend internals (tests/test_layering.py at the repo root).

Local files, both directions

A path you give analyze_source is a path on the machine running this server, never on the engine: the file is read here and uploaded, which is the only way a local file becomes usable by an engine running elsewhere. Identical path strings on two machines do not imply identical filesystems, so the path is never passed through untouched.

download_artifact is the mirror image — it brings a finished artifact back to this machine, bounded by CONTENT_MCP_DOWNLOAD_DIR (see above).