discourse/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 --allow_writes is sufficient and deprecates read_only=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)**
Then, in your MCP client, either:
- Call the discourse_select_site 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 discourse_select_site is hidden).
- **Enable writes (opt‑in, safe‑guarded)**
- **Run with only Data Explorer built-in tools**
This exposes discourse_select_site 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**
> Alternative: if you prefer a global binary after install, the package exposes discourse-mcp.
>
>
Configuration
The server registers tools under the MCP server name @discourse/mcp. Choose a target Discourse site either by:
- Using the discourse_select_site 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 discourse_select_site).
- **Auth**
- **None** by default.
- **Admin API Keys** (require admin permissions): **--auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]'**
- **User API Keys** (any user can generate): **--auth_pairs '[{"site":"https://example.com","user_api_key":"...","user_api_client_id":"..."}]'**
- **HTTP Basic Auth** (for sites behind a reverse proxy): Add http_basic_user and http_basic_pass 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 auth_pairs; the matching entry is used for the selected site. If both user_api_key and api_key are provided for the same site, user_api_key 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**
- --help, -h, or positional help: print current CLI help and exit successfully before loading profiles or starting a transport.
- --version, -v, or positional version: print one package-version line and exit successfully. -v means version; logging verbosity uses --log_level.
- --allow_writes (default: false): enable mutation tools. This single explicit opt-in is sufficient.
- --read_only : deprecated compatibility setting. true is an explicit read-only override and conflicts with --allow_writes; false has no effect and should be removed from commands and profiles.
- --timeout_ms (default: 15000)
- --concurrency (default: 4)
- --log_level (default: info)
- debug: Shows HTTP request URLs, statuses, and detailed network/retry information (response bodies are never logged because admin APIs may echo sensitive content)
- info: Shows retry attempts and general operational messages
- error: Shows only errors
- silent: No logging output
- --show_emails (default: false). includes emails in user tools. Requires admin access
- --tools_mode (default: auto)
- --toolsets : Expose selected built-in domains. Omit for the compact default catalog (all non-opt-in domains); use --toolsets all to include opt-in category/group/tag-group, moderation, workflow, and AI administration domains. See Built-in toolsets.
- --site : Tether MCP to a single site and hide discourse_select_site.