# irc-mcp

A small MCP server that gives Claude Code an IRC connection.

- Connects to `irc.rizon.net:6697` over TLS as `tpuahsiew_claude`, and uses a fallback nick if that one is taken
- Answers server PINGs, sends its own keepalive PING, and reconnects automatically
- Can only join channels listed in `allowed_channels` in `config.json` (re-read on every call, so edits apply right away)
- Keeps a rolling buffer of recent messages per joined channel (`buffer_size`, default 200)
- Never posts on its own. It sends chat only through `send_message`, and does not answer CTCP

## Tools

| Tool | What it does |
|---|---|
| `irc_status` | Connection state, nick, joined and allowed channels |
| `join_channel` | Join an allowed channel |
| `leave_channel` | Part a channel |
| `send_message` | Post to a joined channel (max 10 lines, paced 1/s) |
| `read_messages` | Last N buffered messages (`include_events` adds joins, parts, etc.) |
| `list_users` | Nicks currently in a joined channel |

The buffer only holds messages seen since the bot joined in the current Claude Code session.

## Setup (Windows)

```powershell
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt
claude mcp add --scope user irc -- C:\wallpapers\irc-mcp\.venv\Scripts\python.exe C:\wallpapers\irc-mcp\server.py
```

Set `IRC_MCP_CONFIG` to use a config file somewhere else.