ircv3-mcp
Allows connecting to the Libera.Chat IRC network, providing tools for reading channels, sending messages, replying to threads, adding reactions, fetching history, and managing channel membership.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ircv3-mcp show me what's been said in #test recently"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: rivendell
Quickstart
Configure an account with the interactive wizard — run through npx, nothing to install:
npx -y ircv3-mcp@latest configureIt 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-stdinVerify connectivity:
npx -y ircv3-mcp@latest test liberaThen register the server with your agent and the tools listed below become available immediately:
claude mcp add ircv3-mcp -- npx -y ircv3-mcp@latestTools
Read-only
irc_list_networks— list all configured accounts and their connection statusirc_status— show connection status, nick, and active capabilities for an accountirc_read_history— fetch messages from a channel or DM as a rendered transcriptirc_list_conversations— list channels and DMs that had activity in a time windowirc_list_members— list current members of a channel with mode prefixesirc_whois— look up information about a nick
Writes
irc_send_message— send a message or multiline batch; supports threading viain_reply_toirc_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 notificationirc_react— add or remove an emoji reaction on a messageirc_join— join a channel, optionally with a keyirc_part— leave a channelirc_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
Available Tools
17 toolsirc_joinJoin an IRC channelB
Join a channel, optionally with a key (password).
Inputs: channel (required), key, account. Returns: ok
irc_list_conversationsList active IRC conversationsBRead-only
List channels and DMs that had activity in the given time window.
Inputs: hours, limit, account. Returns: conversations
irc_list_membersList IRC channel membersBRead-only
List the current members of a channel with their mode prefixes.
Inputs: channel (required), account. Returns: members
irc_list_networksList IRC networksARead-only
List configured IRC networks. Each has a state: "connected" (live this session) or "idle" (configured but not connected yet). Idle is normal and not an error — an account connects automatically the first time you use any tool on it. Just use the tools; do not treat idle as a failure.
Inputs: no named parameters. Returns: networks
irc_mark_readMark IRC conversation as readAIdempotent
Send a read marker up to the given timestamp for a target.
Inputs: target (required), timestamp (required), account. Returns: ok
irc_partLeave an IRC channelA
Leave a channel with an optional parting reason.
Inputs: channel (required), reason, account. Returns: ok
irc_reactReact to an IRC messageA
Add or remove an emoji reaction on a message identified by its msgid.
Inputs: emoji (required), msgid (required), target (required), remove, +1 more. Returns: ok
irc_read_historyRead IRC message historyBRead-only
Fetch recent messages from a channel or DM. Use msgid values from results for reply/react/redact.
Inputs: target (required), mode, limit, msgid, +2 more. Returns: markdown, messages
irc_recent_eventsRecent live IRC eventsARead-only
Return recent live IRC events buffered since this session connected: messages, joins/parts/quits, nick/topic/mode changes, and reaction TAGMSGs. To watch for new activity, poll this tool with since_seq set to the cursor returned by the previous call — you get only events after it. Filter by target (a channel or nick) and kinds. This is the live in-memory buffer; for older server-side history use irc_read_history.
Inputs: kinds, limit, target, account, +1 more. Returns: cursor, events
irc_redactRedact an IRC messageADestructive
Redact (delete) a message by its msgid. This is destructive and cannot be undone.
Inputs: msgid (required), target (required), reason, account. Returns: ok
irc_send_messageSend IRC messageA
Send a message to a channel or user. Provide text (single line) or lines (multiline array). Use in_reply_to with a msgid to thread replies. On success returns { ok: true } and, when available, the server-assigned msgid (use it for follow-up reply/react/redact). ok: true means the server confirmed the send — trust it; do not re-read history to verify. A failed or unconfirmed send returns an error, never an empty result.
Inputs: target (required), text, lines, notice, +2 more. Returns: ok, msgid
irc_send_rawSend raw IRC lineADestructive
Send a raw IRC protocol line. Destructive and unrestricted — use only when no higher-level tool fits.
Inputs: line (required), account. Returns: sent
irc_send_with_typingSend IRC message with typing notificationA
Send a message the way a person would: emit a typing notification, hold it for a short time proportional to the message length (about 90 words per minute by default, tunable with wpm), then send the message. Use this for direct conversation where a natural typing indicator is desirable; use irc_send_message when you just want to deliver text immediately. Returns { ok: true } and the msgid when available, same as irc_send_message.
Inputs: target (required), wpm, text, lines, +3 more. Returns: ok, msgid
irc_start_typingStart IRC typing notificationA
Send a typing notification (+typing=active) to a channel or user, signalling that a message is being composed. Clients show this for about 6 seconds, so call again to keep it alive while you work, then send the message or call irc_stop_typing. For one-shot human-like sends, prefer irc_send_with_typing.
Inputs: target (required), account. Returns: ok
irc_statusIRC connection statusBRead-only
Show the current connection status for an IRC account.
Inputs: account. Returns: caps, nick, account, network, +1 more
irc_stop_typingStop IRC typing notificationA
Clear an active typing notification (+typing=done) for a channel or user without sending a message. Use this if you started typing with irc_start_typing but decided not to send.
Inputs: target (required), account. Returns: ok
irc_whoisIRC WHOIS lookupCRead-only
Look up information about a nick on IRC.
Inputs: nick (required), account. Returns: nick, lines, account, channels, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools target clearly distinct actions and resources. The main overlaps are irc_send_message vs irc_send_with_typing and irc_read_history vs irc_recent_events, but the descriptions explicitly separate immediate delivery from typing-indicator sends and server history from the live event buffer, so agents can reliably disambiguate.
All tools share the irc_ prefix and most follow a verb_noun pattern like irc_list_members, irc_send_message, and irc_mark_read. A few names deviate slightly—irc_status, irc_whois, and irc_recent_events are noun-like—but the overall pattern remains predictable and readable.
17 tools is slightly above the typical sweet spot, but each tool maps to a meaningful IRC capability: connection status, history, live events, messaging, typing, reactions, membership, channel join/part, and raw protocol access. None feel redundant enough to remove, and the count is reasonable for an IRC client surface.
The core IRC lifecycle is well covered: join/part, send/reply/react/redact, read history and live events, list members, whois, typing indicators, and read markers. Dedicated tools for topic changes, mode changes, or nick changes are missing, but irc_send_raw provides a workable escape hatch for those operations.
Maintenance
Related MCP Connectors
IRC-style chat server where AI agents and people talk: channels, DMs, claims, approvals.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Sendbird — chat users, channels, members, and messages from your AI client.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for Rocket.Chat, enabling AI agents to interact with Rocket.Chat workspaces via tools like listing users, sending messages, and managing channels.2-
- AlicenseNot gradedqualityAmaintenanceMCP server for Rivendell, a workspace where AI agents collaborate on threaded discussions with resolutions. Provides tools for agents to create threads, reply with structured verdicts, and manage project context.1 npmMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP central server that lets multiple AI agents (e.g., Claude Code, kimi-code) exchange private messages, shared channel broadcasts, and unified message streams via MCP tools, with SQLite persistence and per-connection identity binding.97 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to message each other by @nickname via an MCP server, with contacts, presence, and durable delivery across local and remote agents.3Apache 2.0