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

  1. Create an app at nightbot.tv/account/applications and generate an access token (scopes: channel commands timers regulars spam_protection channel_send).
  2. Provide the token:
export NIGHTBOT_ACCESS_TOKEN=...     # or NIGHTBOT_MCP_SECRETS=vaultproxy
  1. 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

Project links

Data verified by PyPI on Jul 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aaronckj from gravatar.com aaronckj

Credits

Author: aaronckj

GitHub Statistics

Data verified by PyPI on Jul 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

chatbot mcp model-context-protocol moderation nightbot streaming

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nightbot_mcp-0.1.2.tar.gz (8.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nightbot_mcp-0.1.2-py3-none-any.whl (8.2 kB view details)

Uploaded Python 3

File details

Details for the file nightbot_mcp-0.1.2.tar.gz.

File metadata

  • Download URL: nightbot_mcp-0.1.2.tar.gz
  • Upload date:
  • Size: 8.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for nightbot_mcp-0.1.2.tar.gz
Algorithm Hash digest
SHA256 690ec0caec3b601cad3fdee3b8e752f5069003fcd4d8ef9a45cd50d3056a02eb
MD5 cd6950ed01e87fc5346e41347b06e44a
BLAKE2b-256 6f20c0b04002d3c0a29d6185a222cb86a51b699ccde5a0861f80034c1eb28826

See more details on using hashes here.

Provenance

The following attestation bundles were made for nightbot_mcp-0.1.2.tar.gz:

Publisher: publish.yml on aaronckj/nightbot-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nightbot_mcp-0.1.2-py3-none-any.whl.

File metadata

  • Download URL: nightbot_mcp-0.1.2-py3-none-any.whl
  • Upload date:
  • Size: 8.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for nightbot_mcp-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 af36ea6ce174fb2f7d4071d5482e575a33ece80911455d57e73aad8ca4af30a8
MD5 f8075f8febecf616c5377440a8757707
BLAKE2b-256 a7caf784b8c417b41728f0fb6604684cf94e08787e1b534e5b8c730d4bbab095

See more details on using hashes here.

Provenance

The following attestation bundles were made for nightbot_mcp-0.1.2-py3-none-any.whl:

Publisher: publish.yml on aaronckj/nightbot-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 files

0.1.1

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page