Discourse MCP

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)

npx -y @discourse/mcp@latest

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)

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 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

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

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

config.json

Copy

{
  "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 discourse_select_site tool at runtime (validates via /about.json), or

• Supplying --site <url> 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 <boolean>: 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 <number> (default: 15000)

  • --concurrency <number> (default: 4)

  • --log_level <silent|error|info|debug> (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 <auto|discourse_api_only|tool_exec_api> (default: auto)

  • --toolsets <name[,name...]>: 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 <url>: Tether MCP to a single site and hide discourse_select_site.

  • --default-search <prefix>: Unconditionally prefix every search query (e.g., tag:ai order:latest).

  • --max-read-length <number>: Maximum characters returned for post content (default 50000). Applies to discourse_read_post and per-post content in discourse_read_topic and discourse_read_private_message. The tools prefer raw content by requesting include_raw=true.

  • --allowed_upload_paths <paths>: Comma-separated list or JSON array of directories allowed for local file uploads. Required to enable local file uploads in discourse_upload_file. Example: --allowed_upload_paths "/home/user/images,/tmp/uploads" or --allowed_upload_paths '["/home/user/images"]'. These security-sensitive paths do not receive ~ expansion.

  • --transport <stdio|http> (default: stdio): Use standard input/output by default, or loopback-only Streamable HTTP with JSON responses. HTTP explicitly supports one stateful MCP client/session per process. Every post-initialize request must carry the returned Mcp-Session-Id; a second initialize is rejected. After session DELETE/close, restart the process before connecting another client. /health returns 503 restart_required in that closed state. Request bodies are bounded to 4 MiB.

  • --port <number> (default: 3000): Port to listen on when using HTTP transport.

  • --cache_dir <path> (reserved)

  • --profile <path.json> (see below)

• Profile file (keep secrets off the command line)

{
  "auth_pairs": [
    {
      "site": "https://try.discourse.org",
      "api_key": "<redacted>",
      "api_username": "system"
    },
    {
      "site": "https://example.com",
      "user_api_key": "<user_api_key>",
      "user_api_client_id": "<client_id>"
    },
    {
      "site": "https://protected.example.com",
      "api_key": "<redacted>",
      "api_username": "system",
      "http_basic_user": "username",
      "http_basic_pass": "password"
    }
  ],
  "allow_writes": true,
  "show_emails": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org",
  "default_search": "tag:ai order:latest",
  "max_read_length": 50000,
  "transport": "stdio",
  "port": 3000,
  "allowed_upload_paths": ["/home/user/images", "/tmp/uploads"]
}

Run with:

node dist/index.js --profile /absolute/path/to/profile.json
# Current-user home expansion is also supported:
node dist/index.js --profile ~/discourse-mcp-profile.json

Flags still override values from the profile. A leading current-user ~, ~/, or ~\ in the profile path expands to the current home directory; ~otheruser, shell-style expansion elsewhere, and upload-allowlist expansion are intentionally unsupported.

Built-in toolsets

Toolsets let an operator expose only the built-in domains needed by an MCP client. They are optional: when --toolsets and the profile field are both omitted, the server registers the default catalog (including search, discourse_search, and discourse_filter_topics). Administrative and specialized domains marked (opt-in) below—including themes—must be selected explicitly. Use --toolsets all only when every built-in domain is deliberately required.

Pass one name or a comma-separated union:

# Data Explorer reads, plus the site-selection bootstrap tool
npx -y @discourse/mcp@latest \
  --toolsets data_explorer \
  --tools_mode discourse_api_only

# Search and topic tools, retaining canonical registration order
npx -y @discourse/mcp@latest \
  --toolsets search,topics \
  --tools_mode discourse_api_only

# Every built-in domain, including opt-in workflows
npx -y @discourse/mcp@latest \
  --toolsets all \
  --tools_mode discourse_api_only

# Author, test, and run workflows (admin key required)
npx -y @discourse/mcp@latest \
  --toolsets workflows \
  --site https://forum.example.com \
  --auth_pairs '[{"site":"https://forum.example.com","api_key":"...","api_username":"system"}]' \
  --allow_writes \
  --tools_mode discourse_api_only

Profiles use an array (a comma-separated string is also accepted):

{
  "toolsets": ["users", "uploads"]
}

Available toolsets are: