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: