discourse-mcp

A small MCP stdio server that gives an AI agent tools to read and act on a single Discourse forum — a focused, dependency-free Python fork of the official @discourse/mcp.

• Python stdlib only. No Node, no npm, no third-party packages. Talks to Discourse over urllib, speaks MCP (JSON-RPC 2.0, newline-delimited) over stdio.

• Single-site, one identity. Credentials come from the environment; there are no profiles, no multi-site auth_pairs, and no discourse_select_site bootstrap. A bot serves one forum as one user.

• The forum tools a participant needs — plus the ones @discourse/mcp lacks: reading, posting, and private messages, and liking, custom-emoji reactions, bookmarking, watch/track/mute, and reading the bot's own notifications.

Built as the agent's "hands" for discourse-acp (an ACP harness), but it is a plain MCP server — any MCP client can spawn it.

Install

pip install .            # or: pipx install .

Installs a discourse-mcp console script.

Related MCP server: Discourse MCP

Configure (environment)

A global admin key acts as api_username; a per-user key acts as that user. Either way the bot posts as itself — there is no acting-user impersonation.

Run

discourse-mcp            # run the MCP server on stdio (what an MCP client spawns)
discourse-mcp selftest   # drive initialize + tools/list + tools/call, no network
discourse-mcp tools      # print the full tool catalog as JSON

An MCP client (e.g. Claude Code, or claude-agent-acp) spawns it as a stdio server. Example client config:

{ "command": "discourse-mcp",
  "env": { "DISCOURSE_URL": "https://forum.example.com",
           "DISCOURSE_API_KEY": "…", "DISCOURSE_API_USERNAME": "mybot",
           "DISCOURSE_MCP_ALLOW_WRITES": "1" } }

Tools

All names are prefixed discourse_. Read tools are always available; write tools appear only when DISCOURSE_MCP_ALLOW_WRITES=1. Read tools return a compact projection (not raw Discourse JSON) and truncate bodies to DISCOURSE_MCP_MAX_READ_LENGTH.

Reads: search, read_topic, read_post, get_user, list_categories, list_notifications (the bot's own feed — a side-effect-free peek), read_private_message, list_private_messages.

Writes: create_post, create_topic, update_post, create_private_message, reply_private_message, like_post, unlike_post, react_post (custom emoji; needs the discourse-reactions plugin), bookmark, delete_bookmark, watch_topic (muted / regular / tracking / watching).

Relation to @discourse/mcp

This is intentionally not a 1:1 port. The official server exposes ~100 tools across many admin/opt-in toolsets (workflows, themes, webhooks, data-explorer, AI, …). This fork keeps the surface a conversational forum participant actually uses and adds the day-to-day engagement actions the official server omits (likes/reactions/bookmarks/watch, own-notifications). Tool names and the projected read shapes mirror @discourse/mcp where they overlap.

MCP compliance

Protocol version 2025-06-18 (falls back gracefully to the client's requested version). Implements initialize, notifications/initialized, tools/list, tools/call, and ping. NDJSON stdio framing; stdout carries only protocol messages, all logging goes to stderr.