discourse-mcp

Discourse MCP

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

• Entry point: src/index.ts compiled to dist/index.js (binary name: discourse-mcp)
• SDK: @modelcontextprotocol/sdk
• Node: >= 18

Quick start (release)

• Run (readonly, 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 (optin, safeguarded)

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

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

{
  "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":"..."}]'
  • 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.
  • The tools discourse_create_post, discourse_create_topic, discourse_create_category, and discourse_create_user are only registered when all are true:
    • --allow_writes AND not --read_only AND some auth is configured (either default flags or a matching auth_pairs entry).
  • A ~1 req/sec rate limit is enforced for write actions.

• Flags & defaults

  • --read_only (default: true)
  • --allow_writes (default: false)
  • --timeout_ms <number> (default: 15000)
  • --concurrency <number> (default: 4)
  • --log_level <silent|error|info|debug> (default: info)
    • debug: Shows all HTTP requests, responses, and detailed error information
    • info: Shows retry attempts and general operational messages
    • error: Shows only errors
    • silent: No logging output
  • --tools_mode <auto|discourse_api_only|tool_exec_api> (default: auto)
  • --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. The tools prefer raw content by requesting include_raw=true.
  • --transport <stdio|http> (default: stdio): Transport type. Use stdio for standard input/output (default), or http for Streamable HTTP transport (stateless mode with JSON responses).
  • --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>" }
  ],
  "read_only": false,
  "allow_writes": 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
}

Run with:

node dist/index.js --profile /absolute/path/to/profile.json

Flags still override values from the profile.

• Remote Tool Execution API (optional)

  • With tools_mode=auto (default) or tool_exec_api, the server discovers remote tools via GET /ai/tools after you select a site (or immediately at startup if --site is provided) and registers them dynamically. Set --tools_mode=discourse_api_only to disable remote tool discovery.

• Networking & resilience

  • Retries on 429/5xx with backoff (3 attempts).
  • Lightweight inmemory GET cache for selected endpoints.

• Privacy

  • Secrets are redacted in logs. Errors are returned as humanreadable messages to MCP clients.

Tools

Builtin tools (always present unless noted):

• discourse_search
  • Input: { query: string; with_private?: boolean; max_results?: number (150, default 10) }
  • Output: text summary plus a compact footer like:

    { "results": [{ "id": 123, "url": "https://", "title": "" }] }
    

• discourse_read_topic
  • Input: { topic_id: number; post_limit?: number (120, default 5) }
• discourse_read_post
  • Input: { post_id: number }
• discourse_list_categories
  • Input: {}
• discourse_list_tags
  • Input: {}
• discourse_get_user
  • Input: { username: string }
• discourse_filter_topics
  • Input: { filter: string; page?: number (default 1); per_page?: number (150) }
  • Query language (succinct): key:value tokens separated by spaces; category/categorie…