Skip to main content
Glama
ircv3-mcp

ircv3-mcp

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 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

Available Tools

17 tools
irc_joinJoin an IRC channelB

Join a channel, optionally with a key (password).

Inputs: channel (required), key, account. Returns: ok

irc_list_conversationsList active IRC conversationsB
Read-only

List channels and DMs that had activity in the given time window.

Inputs: hours, limit, account. Returns: conversations

irc_list_membersList IRC channel membersB
Read-only

List the current members of a channel with their mode prefixes.

Inputs: channel (required), account. Returns: members

irc_list_networksList IRC networksA
Read-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 readA
Idempotent

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 historyB
Read-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 eventsA
Read-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 messageA
Destructive

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 lineA
Destructive

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 statusB
Read-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 lookupC
Read-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

    A3.6/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Rocket.Chat, enabling AI agents to interact with Rocket.Chat workspaces via tools like listing users, sending messages, and managing channels.
      2
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      MCP 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 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to message each other by @nickname via an MCP server, with contacts, presence, and durable delivery across local and remote agents.
      3
      Apache 2.0