Skip to content

Usage — API / CLI / MCP

owncast-agent exposes the same capability three ways: as MCP tools an agent calls, as a Python API (OwncastApi) the operator import, and as CLI entry points. The tool surface and the underlying Owncast REST contract are summarized in Architecture.

As an MCP server

Once deployed, the server registers one typed tool per Owncast API operation, named owncast_<operation> (for example owncast_get_status, owncast_get_active_viewers, owncast_set_stream_title), plus owncast_ingest_telemetry. Arguments are typed tool parameters; there is no action router and no params_json string.

Example agent prompts that map onto these tools:

  • "What is the current server status and active viewer count?" -> owncast_get_status, owncast_get_active_viewers
  • "Set the stream title to 'Live coding session'" -> owncast_set_stream_title
  • "Send a system message to the chat" -> owncast_send_system_message

As a Python API

OwncastApi is a requests-based facade over the Owncast REST API, composed from per-domain mixins (system, chat, followers, configuration, integrations, auth).

from owncast_agent.api_client import OwncastApi

api = OwncastApi(
    base_url="http://your-owncast:8080",
    token="your_owncast_token",
)

# Reads
status = api.get_status()  # server status
viewers = api.get_active_viewers()  # current active viewers
followers = api.get_followers(limit=50)  # the follower list
hardware = api.get_hardware_stats()  # CPU / memory / disk

Build a client straight from the environment:

from owncast_agent.auth import get_client

api = get_client()  # reads OWNCAST_URL / OWNCAST_TOKEN from the environment / .env

Writes

Configuration and moderation calls map to the same client:

api.set_stream_title("Live coding session")
api.send_system_message({"body": "Welcome to the stream!"})
api.approve_follower(actor_iri="https://example.social/users/alice", approved=True)

As a CLI

Two console scripts are installed with the package:

# Run the MCP server (stdio by default; see Deployment for HTTP transports)
owncast-mcp --transport streamable-http --host 0.0.0.0 --port 8000

# Run the A2A agent server (consumes the MCP tools)
owncast-agent --provider openai --model-id gpt-4o --api-key sk-...

Both expose --help for the full option set:

owncast-mcp --help
owncast-agent --help