nightbot-mcp

An MCP (Model Context Protocol) server for Nightbot: manage custom chat commands, timers, regulars, and spam-protection filters — including the blacklist (banned words/phrases for live chat) — through the official Nightbot API.

Every mutating tool accepts dry_run=true and returns a preview.
add_banned_phrases appends to the blacklist without clobbering it (fetch → merge → update).
No secrets in this repo or logged at runtime.

Quick start

Create an app at nightbot.tv/account/applications and generate an access token (scopes: channel commands timers regulars spam_protection channel_send).
Provide the token:

export NIGHTBOT_ACCESS_TOKEN=...     # or NIGHTBOT_MCP_SECRETS=vaultproxy

Add to your MCP client:

# Claude Code
claude mcp add nightbot -s user -- uvx nightbot-mcp

Tools

Area	Tools
Channel	`channel_info`, `join_channel`, `part_channel`, `send_chat_message`
Commands	`list_commands`, `add_command`, `update_command`, `delete_command`
Timers	`list_timers`, `add_timer`, `toggle_timer`, `delete_timer`
Regulars	`list_regulars`, `add_regular`, `remove_regular`
Spam protection	`get_spam_filter`, `update_spam_filter`, `add_banned_phrases`
Meta	`health_check`

Filters: blacklist, links, caps, symbols, repetitions, emotes. Blacklist entries support Nightbot's * wildcards.

Development

pip install -e '.[dev]'
ruff check src tests && pytest

Tests are fully offline (fake HTTP opener).

License

MIT