MCP server

Discourse MCP

A Model Context Protocol (MCP) stdio server that exposes Discourse forum capabilities as tools and resources for AI agents.

• Entry point: src/index.ts → compiled to dist/index.js (binary name: discourse-mcp)
• SDK: @modelcontextprotocol/sdk
• Node: >= 24
• Version: 0.3.1 (simplifies write opt-in so --allowwrites is sufficient and deprecates readonly=false; 0.3.0 added operator-selectable toolsets, structured directory output, and expanded opt-in administration capabilities; 0.2.x introduced breaking changes from 0.1.x, including JSON-only tool output; category/group resources remain deprecated compatibility surfaces alongside canonical list tools)

Quick start (release)

• Run (read‑only, recommended to start)

npx -y @discourse/mcp@latest

Then, in your MCP client, either:

• Call the discourseselectsite tool with { "site": "https://try.discourse.org" } to choose a site, or
• Start the server tethered to a site using --site https://try.discourse.org (in which case discourseselectsite is hidden).

• Enable writes (opt‑in, safe‑guarded)

npx -y @discourse/mcp@latest --allow_writes --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'

• Run with only Data Explorer built-in tools

npx -y @discourse/mcp@latest --toolsets data_explorer --tools_mode discourse_api_only

This exposes discourseselectsite plus the read-only Data Explorer tools. Add --site, authentication, and the write flags as needed; see Built-in toolsets.

• Use in an MCP client (example: Claude Desktop) — via npx

{
  "mcpServers": {
    "discourse": {
      "command": "npx",
      "args": ["-y", "@discourse/mcp@latest"],
      "env": {}
    }
  }
}

Alternative: if you prefer a global binary after install, the package exposes discourse-mcp.

json

{

"mcpServers": {

"discourse": { "command": "discourse-mcp", "args": [] }

}

}

Configuration

The server registers tools under the MCP server name @discourse/mcp. Choose a target Discourse site either by:

• Using the discourseselectsite tool at runtime (validates via /about.json), or
• Supplying --site to tether the server to a single site at startup (validates via /about.json and hides discourseselectsite).

• Auth

• None by default.
• Admin API Keys (require admin permissions): --authpairs '[{"site":"https://example.com","apikey":"...","apiusername":"system"}]'**
• User API Keys (any user can generate): --authpairs '[{"site":"https://example.com","userapikey":"...","userapiclientid":"..."}]'
• HTTP Basic Auth (for sites behind a reverse proxy): Add httpbasicuser and httpbasicpass to any auth_pairs entry. This is useful for Discourse sites protected by HTTP Basic Authentication at the reverse proxy level.
• You can include multiple entries in authpairs; the matching entry is used for the selected site. If both userapikey and apikey are provided for the same site, userapikey takes precedence.

• Write safety

• Writes are disabled by default.
• Built-in write tools are only registered when --allow_writes is enabled. This includes post, topic, private-message, category, user, upload, draft, and saved Data Explorer query mutations.
• Private-message listing and reading also require a matching authenticated site because PM data is never public.
• Toolset selection does not bypass write safety. A selected write tool remains absent unless writes are enabled.
• Write tools require a matching auth_pairs entry for the selected site; otherwise they return an error.
• A ~1 req/sec rate limit is enforced for write actions.

• Flags & defaults

Shortened. The full README is on GitHub.