owncast

MCP connector for a self-hosted Owncast 0.3.0 server. It speaks the HTTP API over stdio and over stateless Streamable HTTP on localhost.

Owncast is MIT software. This connector does not copy that code. It only calls the HTTP API on the server you configure. It is not affiliated with Owncast.

owncast.routes.json maps every operation in Owncast 0.3.0 openapi.yaml. scripts/gen-operations.mjs writes src/operations.ts from that table. Do not edit src/operations.ts by hand. The spec lists 239 operations. 117 are tools. 122 are excluded (CORS OPTIONS, browser IndieAuth and Fediverse OTP, player metrics, Prometheus proxy, multipart uploads, and the public-page remote follow form).

OWNCAST_URL is required. There is no default origin.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.

{
  "mcpServers": {
    "owncast": {
      "command": "node",
      "args": ["/workspace/connectors/owncast/dist/index.js"],
      "env": {
        "OWNCAST_URL": "http://127.0.0.1:8095",
        "OWNCAST_ADMIN_PASSWORD": "...",
        "OWNCAST_ACCESS_TOKEN": "...",
        "OWNCAST_ALLOW_WRITES": "false",
        "OWNCAST_TOOLSETS": "status,chat,config"
      }
    }
  }
}

You can set OWNCAST_ADMIN_PASSWORD, OWNCAST_ACCESS_TOKEN, or both. Public routes need neither. Admin routes need the password. Integration routes need the access token.

Docker (HTTP, no authentication, keep it on localhost):

docker build -t owncast-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -e OWNCAST_URL=http://127.0.0.1:8080 \
  -e OWNCAST_ADMIN_PASSWORD=... \
  owncast-mcp

Do not put passwords or tokens in the image.

Regenerate the registry after an OpenAPI bump.

npm run gen:operations

scripts/live-check.mjs talks to a real server over stdio. It needs OWNCAST_URL and OWNCAST_ADMIN_PASSWORD (or /workspace/tools/owncast/admin.pw). It sets OWNCAST_TOOLSETS=all and unsets DATABASE_URL. Gated writes run only when OWNCAST_ALLOW_WRITES=true. It prints pass or fail lines only.

Related MCP server: habitica-mcp

Config

Invalid values are reported by field name and issue code. The rejected value is not included. Passwords, access tokens, stream keys, webhook secrets, and authorization headers are redacted in logs, errors, tool results, thrown messages, and URLs.

Auth is chosen per route. Public paths send no credentials. /api/admin sends Authorization: Basic for user admin. /api/integrations sends Authorization: Bearer. The connector never puts credentials in the API URL.

Safety

GET is a read. POST, PUT, PATCH, and DELETE are writes.

A write needs confirm: true as a boolean and OWNCAST_ALLOW_WRITES=true. The string "true" is rejected. Otherwise the tool returns a dry-run preview of method, path, query, and redacted body, and it sends nothing. Destructive actions add a warning on the tool and on the preview. That set covers disconnecting the inbound stream, changing stream keys or the admin password, banning or disabling users, and deleting webhooks or access tokens.

Access token create and webhook create return the secret once, with a shown-only-once note. Later list calls redact it. Admin config reads redact streamKeys, key, adminPassword, and webhook secret fields. Error text drops stack traces and filesystem paths.

HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 404 is not found. HTTP 400 and 422 are invalid input. HTTP 429 includes Retry-After. Other failures are server, network, or timeout. Response bodies are capped at 1,000,000 bytes.

Tools

Default OWNCAST_TOOLSETS publishes 3 tools. OWNCAST_TOOLSETS=all publishes 7 tools (117 operations, 39 reads and 78 writes). Each tool takes action plus optional params, query, body, and confirm.

action help with optional target returns the path, query, and body fields for one action. Descriptions list action names only, so the tool list stays small.

owncast_status covers public info (/status, /config, emoji, YP, ping, followers) plus integration status. owncast_chat reads chat and sends integration, system, and action messages. owncast_config is admin reads, including server config with stream keys redacted. owncast_moderation hides or shows messages, bans IPs, and manages moderators. owncast_webhooks covers webhooks and access tokens. owncast_ops disconnects the inbound stream and related server actions.

What this is not

This is not the Owncast web UI, the admin dashboard, or an RTMP ingest. It does not start Owncast. It does not upload logos, favicons, or custom emoji files. It does not proxy Prometheus. It does not complete IndieAuth or Fediverse OTP in a browser.

Compared with other Owncast MCP servers

A GitHub search for owncast mcp and owncast mcp-server on 3 Nov 2026 found no Owncast MCP server.

Nearest alternatives that talk to Owncast, without MCP:

• SleepyLili/tlapbot is a Python Flask bot for Owncast channel points and redeems.

• glyphscribe/owncastparser is a Home Assistant integration for Owncast status.

• owncast/plugin-sdk is the official plugin SDK.

This connector adds confirm-gated writes with dry-run previews, per-route public/admin/integration auth, stream-key redaction, toolset scoping, vitest coverage, and a live check against Owncast 0.3.0.

License

MIT. Owncast itself is also MIT. See owncast/owncast.