ircv3-mcp

An IRCv3 MCP server: a mini IRC client that agents drive over the Model Context Protocol. The agent reads channels as rendered chat transcripts, sends messages, replies to threads, adds reactions, fetches history, and manages channel membership — all through a standard set of MCP tools backed by a full IRCv3 connection with SASL authentication.

Install

Requires Node >= 20. Nothing to install — it runs through npx and always pulls the latest published version.

Setup is two steps, both in the Quickstart below: first configure an IRC account (host, nick, SASL), then register the server with your agent. The agent has nothing to talk to until at least one account is configured.

Quickstart

Configure an account with the interactive wizard — run through npx, nothing to install:

npx -y ircv3-mcp@latest configure

It prompts for host, nick, SASL mechanism (one of PLAIN, EXTERNAL, or SCRAM-SHA-256), and a hidden password, and stores the password in your OS keychain.

Prefer a one-liner? add-account reads the password from stdin so it never hits shell history:

echo 'hunter2' | npx -y ircv3-mcp@latest add-account libera \
  --host irc.libera.chat \
  --nick mybot \
  --sasl PLAIN \
  --account mybot \
  --channels '#test' \
  --default \
  --password-stdin

Verify connectivity:

npx -y ircv3-mcp@latest test libera

Then register the server with your agent and the tools listed below become available immediately:

claude mcp add ircv3-mcp -- npx -y ircv3-mcp@latest

Tools

Read-only

• irc_list_networks — list all configured accounts and their connection status
• irc_status — show connection status, nick, and active capabilities for an account
• irc_read_history — fetch messages from a channel or DM as a rendered transcript
• irc_list_conversations — list channels and DMs that had activity in a time window
• irc_list_members — list current members of a channel with mode prefixes
• irc_whois — look up information about a nick

Writes

• irc_send_message — send a message or multiline batch; supports threading via in_reply_to
• irc_send_with_typing — send a message after a length-proportional typing notification (~90 wpm)
• irc_start_typing / irc_stop_typing — manually raise or clear a typing notification
• irc_react — add or remove an emoji reaction on a message
• irc_join — join a channel, optionally with a key
• irc_part — leave a channel
• irc_mark_read — advance the read marker for a conversation

Destructive

• irc_redact — delete a message by msgid (cannot be undone)
• irc_send_raw — send a raw IRC protocol line (unrestricted)

Configuration

Accounts are stored in TOML at ~/.config/ircv3-mcp/config.toml. The XDG XDG_CONFIG_HOME variable is respected; the path can also be overridden with IRCV3_MCP_CONFIG_DIR.

Passwords are never stored in the config file, in tool output, or in logs. The server stores them in the OS keychain (@napi-rs/keyring) and falls back to an AES-256-GCM encrypted file (secrets.enc) when the keychain is unavailable. The encryption key comes from a 0600 keyfile (secrets.key) or the IRCV3_MCP_SECRET_KEY environment variable.

See docs/config.example.toml for an annotated example.

Persistence

The server is stateless per session: it opens one IRC connection per configured account when the agent session starts and uses draft/chathistory to catch up on messages since the last read marker.

For gap-free 24/7 presence — keeping the connection alive between agent sessions and accumulating full history — point ircv3-mcp at a bouncer such as soju or ZNC, or an always-on server such as Ergo or ObbyIRCd.

Development

npm run ci       # typecheck + lint + test + build (mirrors CI)
npm test         # vitest unit tests only
npm run build    # compile to dist/

Integration tests against a live Ergo instance are gated by IRC_IT=1 and are not yet wired into the default test run. Set that variable to opt in when running locally against a test server.

License

MIT