notify-human-mcp

An MCP server that gives your LLM a way to reach you on Discord whenever it needs your attention — a question it can't answer itself, a blocker, a decision it needs from you, something worth knowing mid-task, or work that's finished. Not just an end-of-task bell: a general human-attention channel. Every message arrives in a standardized format you control from a file, not from each model's habits.

The server reads your instructions file at every client launch and hands the text to the MCP client as its instructions field. The client injects it into the LLM's system prompt each session — the same effect as AGENTS.md, per tool. Edit the file, and the next session on that machine uses the new format. That text lives in the conversation history, so it is summarized away when the conversation is compacted; the send tool description therefore also carries the file path with a conditional hint to re-read it if the rules are no longer in context.

One tool is exposed:

If no webhook URL is configured, send fails with a clear error and posts nothing.

Install

Requires uv. The package is not on PyPI yet, so install from the repository:

uvx --from git+https://github.com/Ruxconk/notify-human-mcp.git notify-human-mcp

Related MCP server: Chat Human MCP Server

Per-machine setup

Add one block to your MCP client's config (Claude Desktop, Codex CLI, etc.):

"notify-human": {
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/Ruxconk/notify-human-mcp.git",
    "notify-human-mcp"
  ],
  "env": {
    "NOTIFY_HUMAN_WEBHOOK_URL": "https://discord.com/api/webhooks/…",
    "NOTIFY_HUMAN_INSTRUCTIONS_FILE": "/path/to/your-instructions.md"
  }
}

For a local checkout, replace the git URL with the directory path: "--from", "/path/to/notify-human-mcp".

Instructions are resolved in order: file → URL → built-in default. A missing file or failed fetch falls through silently — the server always starts.

Restart the MCP client after changing anything. A stdio server is one long-lived process: it reads its code, its env and the instructions file at launch and never looks again. Editing the instructions file, changing an env var, or shipping a new version does nothing until the client restarts the server — and when you install from a local path, uvx caches the built wheel per content hash, so a rebuilt package needs that same restart to take effect. If notifications come back in the old format after you edited the file, this is why.

Two instruction modes

Prose mode (default): a .md/.txt file of plain-language rules. The LLM reads them and tries to comply — flexible, zero setup, best-effort.

Template mode: point NOTIFY_HUMAN_INSTRUCTIONS_FILE at a .json file and the format is enforced by construction. send then takes named fields — status, title, body, optional ticket, agent, model, repo — and the server assembles the message from the template, so the shape cannot drift. An unknown status or a missing field is rejected with the reason, nothing posted. Structure:

{
  "header": "{time} | {repo} — {title} {status_emoji}",
  "lines": ["{ticket}", "agent: {agent} | model: {model} | Machine: {machine}"],
  "statuses": {"done": "✅", "blocked": "🛑", "question": "❓"},
  "max_chars": 1000,
  "embed": true,
  "guidance": "Address him as Rux. Short bullets, one fact each; no raw logs."
}

Only header and statuses are required. Placeholders for header/lines: time, repo, title, status_emoji, ticket_line, ticket, agent, model, machine. ticket_line renders ticket: X; ticket renders the raw value verbatim (e.g. ENG-142 — rotate deploy keys); agent names the agent sending the ping. A line that renders empty (no ticket, say) is dropped. max_chars is a hard ceiling on the rendered message. embed: true posts a rich card instead of a plain message, which lifts the Discord limit from 2000 to 4096 characters. guidance is free text appended to the instructions the LLM receives — the place for tone, persona and "when to ping" rules that a fixed structure cannot express. Working examples: examples/ (template-minimal.json, template-full.json, template-team.json) — copy one and edit the values. Startup logs the mode and source on stderr; if a prose file and a same-stem .json both exist, JSON wins, and a broken JSON file is reported loudly rather than silently downgrading to prose.

Writing the instructions file

This file is the format control — and it decides when the LLM may ping you, not just how. Example:

Use the `send` tool whenever the human's attention is needed: you are blocked, you
need a decision or missing information, something important happened mid-task, or
you finished. One message per event — no play-by-play.
Format: one-line status first (done / blocked / needs input / FYI), then a short
summary, then what you need from the human (if anything). Keep it under 1000
characters. No raw logs.

Point several machines at the same file contents (or the same hosted URL) to get one format everywhere; give a machine its own file to diverge.

Trust note: a hosted instructions URL is a control point — whoever can edit that URL controls what every connected LLM is told. Keep it private and writeable only by you.

Development

uv sync                          # env + dev deps
uv run pytest -q                 # 85 tests, HTTP mocked or loopback-only, zero real sockets
uvx ruff check src tests         # lint
uvx ruff format --check src tests
uv build                         # sdist + wheel into dist/

Publishing (prepared — not yet run)

First, create a PyPI account and (recommended) an API token scoped to the project. Then:

uv build                            # dist/notify_human_mcp-<ver>.tar.gz + .whl
uv publish                          # or: pipx run twine upload dist/*

Bump version in pyproject.toml for each release.

Optional, later: list the package in the public MCP Registry so others can discover it. The registry is still in preview, stores metadata only, and verifies repo ownership — a discovery nicety, never needed for your own machines.

License

MIT — see LICENSE.