Skip to main content
Glama
mirc-mcp
by b1tninja

mirc-mcp

A local MCP server (stdio only) that lets an MCP client read from and write to a running mIRC on the same Windows PC, through a restricted bridge.

It adds no network exposure. The server talks to mIRC with mIRC's documented SendMessage interface: a window message plus a 4 KiB named shared-memory mapping inside your Windows session. There is no socket, no port and no DDE, and the mIRC side (mirc/mcp-bridge.mrc) opens no socket and starts no DCC. The MCP client starts the server as a child process and talks to it over stdin/stdout.

Why this design

No MCP server for mIRC existed when this was written (2026-11-07). The IRC MCP servers that do exist (tbarron-xyz/mcp-irc-ts, matheusfillipe/ircv3-mcp, jbanier/irc-mcp, ...) are IRC clients in their own right. They would open their own connection, bypassing any proxy or connect guard you have set up in mIRC, so they are the wrong tool for driving an existing client.

Way to drive mIRC

Network?

Verdict

SendMessage WM_MCOMMAND/WM_MEVALUATE + mIRCN mapping

none

used: documented, synchronous, returns results, ctypes only

DDE (mIRC service, COMMAND/EVALUATE)

none

works, but legacy, and any local program can use it. Consider turning it off (Options > Other > DDE) since nothing here needs it

Script socket bridge (socklisten 127.0.0.1)

a listening TCP port

rejected: a port that any local process (or a browser via DNS rebinding) can reach

Reading log files

none

read-only, needs logging to disk, and has no send

Related MCP server: mcp-bridge

What it exposes

Tool

Does

list_connections

cid, status, server, network, nick, and whether policy allows it

list_windows(cid)

joined channels (users, topic) and open queries

read_messages(cid?, window?, after_seq, limit)

recent TEXT/ACTION/NOTICE/own lines from the bridge's in-memory ring buffer (500 entries, never written to disk)

send_message(cid, target, text, kind)

msg / notice / action to an allowlisted target

irc_command(cid, command, target, text)

one of join part whois names topic (default allows whois names topic)

evaluate_identifier(cid, name, args, prop)

one allowlisted identifier, e.g. $chan(#x).topic

audit_settings()

reads fixed leak-relevant mirc.ini keys (proxy, identd, DDE, update check, Favorites on connect, Local Info lookup method) after /saveini and lists problems; the SOCKS password key is never read. The lookup method is [options] n2 field 4 on 7.86 (0 Normal, 1 Server, 2 Website); "Website" is flagged because it fetches your IP from a web site, possibly outside the proxy

harden_settings(tor_port)

tightening only: /proxy -cm5+d 127.0.0.1 <port> and /proxy on (SOCKS5, DCC included, user/password cleared), /identd off, /ddeserver off. The port must be in tor_socks_ports (default 9050, 9150); allow_harden = false removes the tool

mirc_status(lines)

read-only: pid, version, $status/$server, each connection (status, server, port, ssl), the last N status-window lines, open dialogs, loaded scripts. Works without mcp-bridge.mrc

list_dialogs() / close_dialog(title)

list mIRC's open modal dialogs; cancel one of mIRC Options, mIRC Favorites, mIRC Connection Help, About mIRC (closed with its OK once mIRC enables it), mIRC SSL Certificate Warning (Cancel = refuse the cert). Cancel never applies a change

list_scripts() / reload_script(name)

list loaded remote scripts; /reload -rs one that is already loaded, by file name. It cannot load a new script. allow_reload = false removes it

guard_connect(wait_seconds)

runs exactly one alias, connect_alias (empty by default, so the tool is off until you name your guard's alias in policy.toml), which must already be loaded, then reports connected, cert_failure, resolve_failure, proxy_failure, guard_blocked, refused or pending, with the new status lines. It never runs /server, and by default (require_proxy_for_connect) it refuses unless mIRC's SOCKS5 proxy is on 127.0.0.1 with a Tor port, so a .onion name can never go to Windows DNS. connect_alias = "" removes it

pin_certificate(sha256, host, port, restart)

trusts a server certificate by SHA-256 (see below). allow_pin = false removes it

apply_mts_theme(path, scheme, dry_run) / restore_appearance(backup)

applies only the appearance of a local .mts theme (MTS 1.x): the 26 Colors items, the 16-colour RGBColors palette and FontDefault, as /color and /font commands built from validated numbers. Theme code (Script, !Script event lines, Load/Unload), images, sounds and engines/DLLs are never used and are listed as ignored. dry_run (default) changes nothing; applying first saves the current appearance to %LOCALAPPDATA%\mirc-mcp\appearance-*.json, which restore_appearance puts back. allow_theme = false removes both

disable_favorites_on_connect(restart)

turns off "Show favorites on connect" ([options] n4, field 19 on 7.86), whose modal dialog blocks script events on every connect. Unticks it in the open Favorites dialog, or with restart=true closes mIRC, changes only that field in mirc.ini (one-time backup), and starts mIRC again. audit_settings reports it

Settings are changed with mIRC's own commands rather than by editing mirc.ini, because mIRC rewrites that file from memory on exit and would undo an edit made while it runs.

Nick leak through a bouncer (verified on 7.86)

mIRC registers with its configured nick ($mnick). When a bouncer welcomes it under that nick and then renames it, mIRC sends USERHOST <configured nick> to the network straight after the welcome. Unticking Options > Connect > Local Info does not stop this. The fix is to set mIRC's configured nick to the bouncer's nick. mirc_status warns while the two differ.

Included theme

themes/phosphor.mts is an original appearance-only MTS theme: green phosphor on black in Consolas 14 pt (a negative MTS font size is a point size), like an old terminal. Notices and CTCP are amber, highlights yellow, kicks red, and colours 2 and 12 (the blues bots and servers use for links) are a bright cyan-blue. Every palette colour has at least 7:1 contrast on the black background (WCAG AAA). Scheme 1 is an amber CRT. It contains no script, event, image or sound lines, so it is safe with any MTS engine. Try it with apply_mts_theme("themes/phosphor.mts") (dry run), then dry_run=false.

CRT scanlines

themes/phosphor-scanlines.bmp (made by tools/make_scanlines.py) is an 8x3 tile of faint green scanlines for Phosphor: two black rows and one green line, as bright as it can be while every palette colour keeps at least 4.5:1 contrast on the line (main text 10:1). Copy it into mIRC's folder and tile it with mIRC's own command (verified on 7.86: -s is the status window, -e with # or = sets the default for every channel or query window):

/background -st "phosphor-scanlines.bmp"
/background -et # "phosphor-scanlines.bmp"
/background -et = "phosphor-scanlines.bmp"

/background -sx, -ex #, -ex = remove them. Glow and screen curvature need a shader overlay such as ShaderGlass; mIRC has no way to draw them.

Digital rain and CRT glow

themes/phosphor-rain-tile.png (made by tools/make_rain.ps1 -Tile) is an original, seamless "digital rain" tile: half-width katakana, digits and symbols falling in columns, with the scanlines baked in. No pixel is brighter than (0,54,19), so every Phosphor colour keeps at least 4.5:1 contrast anywhere on it. Show it tiled (-t), so it covers a window of any size at 1:1 with no stretching:

/background -st "phosphor-rain-tile.png"
/background -et # "phosphor-rain-tile.png"
/background -et = "phosphor-rain-tile.png"

-Seed gives another pattern. Without -Tile the script makes one full-screen picture instead (themes/phosphor-rain.png, 2560x1440), which only fills a window up to that size.

Nick colour in messages

mIRC's own nick colours (/cnick) colour the nicklist only, never the nick inside a message line (verified on 7.86). mirc/phosphor-nicks.mrc is a small display-only script that redraws incoming channel and private messages and actions so each nick has its own colour and the text stays in "normal" or "action". The colour comes from an MD5 hash of the lower-cased nick, so a nick looks the same everywhere and after restarts. It picks from nine of mIRC's fixed extended colours (grey, lavender, olive, teal, orange, mint, pink, peach, magenta), each 7.9:1 or better on black and kept away from the message green, kicks, highlights, links and parts; with nine colours some nicks will share one. Edit pn.palette to change the set. It only echoes and halts the default line: it sends nothing and leaves CTCP alone. Your own lines are drawn by mIRC itself and keep the "own" colour. Load it with /load -rs phosphor-nicks.mrc.

Certificate pinning

mIRC 7.86 remembers certificates in servers.ini under [sslcache] as nN=<SHA-1>,<subject CN>,<IP connected to>,<flag>. Through a SOCKS proxy mIRC never learns the IP, so for a .onion reached via Tor the third field is empty; pin_certificate therefore writes that empty-host form too when you pin a .onion host (verified on 7.86: without it the pinned certificate was still rejected through the proxy). Ticking "Automatically accept this certificate in future" writes flag 1. Tested on 7.86: an entry with flag 1 is honoured even when Options > Connect > SSL rejects invalid certificates ([ssl] warn=0), so pinning needs no weaker setting. Hostname checks don't apply, which suits a bouncer with a self-signed certificate.

pin_certificate makes one TLS handshake to fetch the certificate the server presents. For a loopback host it connects directly; for a .onion host it goes through the first tor_socks_ports entry on 127.0.0.1. Either way the only socket opened is to 127.0.0.1. If the presented SHA-256 differs from the one you passed, nothing is written. On a match it adds or updates the [sslcache] line and keeps a one-time servers.ini.mirc-mcp.bak. Because mIRC rewrites servers.ini from memory, mIRC must be closed. With restart=true the tool closes it (/exit -n), writes the entry, and starts the same executable again with -noconnect. Use the host exactly as you connect to it: 127.0.0.1 for a local relay, or the .onion name.

mIRC and Tor: what was verified (mIRC 7.86, 2026-11-07)

  • With the SOCKS5 proxy on, mIRC hands a .onion name to the proxy unresolved. A fake SOCKS5 server received CONNECT ATYP=3 <name>.onion:6697, and the Windows DNS cache had no entry for the name. So pointing mIRC at Tor's SOCKS port is enough to reach an onion service; no relay or torsocks-style wrapper is needed.

  • With the proxy off, mIRC asks Windows DNS for the name and fails with "Unable to resolve server". That leaks the onion name to your DNS resolver. RFC 7686 §2 says applications that don't implement Tor "SHOULD NOT perform a DNS lookup" for .onion.

  • With the proxy on, 127.0.0.1 targets go through the proxy too (ATYP=1 127.0.0.1), so a local relay stops being reachable once the proxy is on.

  • mIRC can contact www.mirc.com (port 443) at startup outside any proxy, even with [update] check=0. A fresh unregistered instance did so in every run. The proxy settings don't cover this, so block mirc.exe outbound in Windows Firewall if mIRC must never touch the network itself.

Earlier reports of the same .onion problem in other clients: the mIRC forum on SOCKS5 and DNS, an AdiIRC thread where a DNS check before proxying broke .onion, and the TripSit Tor proxy guide.

There is deliberately no raw command and no raw evaluate tool. Evaluating an arbitrary mIRC expression is code execution ($dll, $com, custom aliases), and a raw command could start a /server, /dcc or /run.

Layers of the guard

  1. Python policy (policy.py): the address mIRC dialled ($server(-1), not the name the server announces, which through a bouncer is e.g. irc.znc.in) must match allowed_servers (default *.onion), and targets must match allowed_targets (default #*, so no private messages until you list nicks). Channels must already be joined. Text may not contain \x01 (no CTCP, so no DCC offer), CR/LF or NUL, and is capped at 400 bytes. Identifier arguments may not contain $ % ( ) , [ ] | or whitespace, so they cannot nest an evaluation. The policy file can only narrow the built-in lists; naming an unsupported verb or identifier is an error.

  2. Transport: all user text and targets reach mIRC base64-encoded in a single /mcp.do <cid> <verb> <b64> <b64> line, so mIRC never parses them for |, $ or %.

  3. mIRC script (mcp-bridge.mrc): re-checks the verb list, rejects \x01, =nick (DCC chat) targets, comma lists and join 0.

  4. Anything else you already run (a connect-guard script in mIRC, CTCP/DCC filtering on a bouncer) stays in force; the bridge adds no way around it.

What this does not protect against: any program running as you can already send these window messages (or DDE) to mIRC directly. The bridge limits what the MCP client can do; it does not sandbox your user account. As a mIRC-side backstop, consider Options > Other > Lock to disable /run, /dll, /com and DCC.

Install

cd mirc-mcp
uv venv -p 3.14 .venv
uv pip install -p .venv\Scripts\python.exe -e ".[dev]"

Copy mirc/mcp-bridge.mrc to %APPDATA%\mIRC\ and load it once in mIRC:

/load -rs "%APPDATA%\mIRC\mcp-bridge.mrc"

Optional: copy policy.example.toml to %APPDATA%\mirc-mcp\policy.toml and edit it (or point MIRC_MCP_POLICY at another file). If several mIRC instances are open, MIRC_MCP_PID selects one.

Register with Claude Code (stdio):

claude mcp add mirc -- <path-to>\mirc-mcp\.venv\Scripts\python.exe -m mirc_mcp

Caveat: modal dialogs pause the buffer. While any modal dialog is open in mIRC (Options, About, Favorites), mIRC still displays incoming lines but runs no script events, so read_messages sees nothing new until the dialog closes. Sending and evaluating still work.

Tests

  • pytest: policy unit tests, which need no mIRC.

  • python tools\smoke.py: an end-to-end test (61 checks, all passing on mIRC 7.86 on 2026-11-07). It starts a throwaway mIRC with its own settings folder (-r <temp> -noreg -noconnect, no update check, identd off) and drives it by process id against a fake IRC server on 127.0.0.1. A background thread closes that instance's own first-run dialogs (the evaluation nag only once its OK button is enabled), because they would block script events. At the end the test kills the instance and deletes its profile. Your own mIRC and profile are never addressed.

  • python tools\sandbox.py: runs the same smoke test inside Windows Sandbox with networking disabled. It maps mIRC, Python and this folder read-only and has one writable output folder. Written but not yet run: the sandbox was in use.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Bridge that lets stdio-only MCP clients connect to remote MCP servers with OAuth and other auth support, enabling local clients to use remote, authorized MCP servers.
      48 npm
      54
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A local stdio MCP server that bridges remote Streamable HTTP MCP servers to MCP clients, enabling transport normalization and optional outbound HTTP proxy support for restricted networks.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables stdio-only MCP clients like Claude Desktop to connect to a running OpsMaxx desktop app by relaying messages to its authenticated HTTP MCP bridge, so they receive the same access controls, approvals, secret redaction, and audit logging as HTTP clients.
      107 npm
      MIT