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. The LLM never sees the file path or URL, only the text.

One tool is exposed:

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

Install

Requires uv. No install step needed — uvx fetches and runs it:

uvx 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": ["notify-human-mcp"],
  "env": {
    "NOTIFY_HUMAN_WEBHOOK_URL": "https://discord.com/api/webhooks/…",
    "NOTIFY_HUMAN_INSTRUCTIONS_FILE": "/path/to/your-instructions.md"
  }
}

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 client after editing the file; the server re-reads it on every launch.

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                 # 57 tests, HTTP fully mocked, zero real sockets
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.