Discourse MCP

🚀 Discourse MCP

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

🚀 Quick Start

Release Version

• Run (Read-only, Recommended for Initial Start)

npx -y @discourse/mcp@latest

Then, in your MCP client, you can either:

• Call the discourse_select_site tool with { "site": "https://try.discourse.org" } to choose a site.

• Start the server tethered to a site using --site https://try.discourse.org (in this case, discourse_select_site is hidden).

• Enable Writes (Opt-in, Safe-guarded)

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 installation, the package exposes discourse-mcp.

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

✨ Features

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

📦 Installation

The project requires Node >= 18 and pnpm. You can install the dependencies using the following command:

pnpm install

💻 Usage Examples

Read-only session against try.discourse.org

npx -y @discourse/mcp@latest --log_level debug
# In client: call discourse_select_site with {"site":"https://try.discourse.org"}

Tether to a single site

npx -y @discourse/mcp@latest --site https://try.discourse.org

Create a post (writes enabled)

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"}]'

📚 Documentation

Configuration

The server registers tools under the MCP server name @discourse/mcp. You can choose a target Discourse site in the following ways:

• Use the discourse_select_site tool at runtime (validates via /about.json).
• Supply --site <url> to tether the server to a single site at startup (validates via /about.json and hides discourse_select_site).

Auth

• By default, no authentication is required.
• You can use --auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]' to set per-site API key overrides. You can include multiple entries, and the matching entry will be used for the selected site.

Write safety

• Writes are disabled by default.
• The tool discourse.create_post is only registered when all of the following conditions are met:
  • --allow_writes is set.
  • --read_only is not set.
  • Some authentication is configured (either default flags or a matching auth_pairs entry).
• A rate limit of approximately 1 request per second is enforced for create_post.

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)
• --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-post).
• --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.
• --cache_dir <path> (reserved)
• --profile <path.json> (see below)

Profile file

You can use a profile file to keep secrets off the command line. Here is an example:

{
  "auth_pairs": [
    { "site": "https://try.discourse.org", "api_key": "<redacted>", "api_username": "system" }
  ],
  "read_only": false,
  "allow_writes": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org",
  "default_search": "tag:ai order:latest-post",
  "max_read_length": 50000
}

You can run the server with the profile file using the following command:

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

Note that 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. You can set --tools_mode=discourse_api_only to disable remote tool discovery.

Networking & resilience

• The server retries on 429/5xx with backoff (3 attempts).
• It uses a lightweight in-memory GET cache for selected endpoints.

Privacy

• Secrets are redacted in logs. Errors are returned as human-readable messages to MCP clients.

Tools

Built-in tools (always present unless noted):

• discourse_search
  • Input: { query: string; with_private?: boolean; max_results?: number (1–50, 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 (1–20, 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 (1–50) }
  • Query language (succinct): key:value tokens separated by spaces; category/categories (comma = OR, =category = without subcats, - prefix = exclude); tag/tags (comma = OR, + = AND) and tag_group; status:(open|closed|archived|listed|unlisted|public); personal in: (bookmarked|watching|tracking|muted|pinned); dates: created/activity/latest-post-(before|after) with YYYY-MM-DD or relative days N; numeric: likes[-op]-(min|max), posts-(min|max), posters-(min|max), views-(min|max); order: activity|created|latest-post|likes|likes-op|posters|title|views|category with optional -asc; free text terms are matched.
• discourse_create_post (only when writes enabled; see Write safety)
  • Input: { topic_id: number; raw: string (≤ 30k chars) }

Notes

• Outputs are human-readable first. Where applicable, a compact JSON is embedded in fenced code blocks to ease structured extraction by agents.

🔧 Technical Details

Development

• Requirements: Node >= 18, pnpm.
• Install / Build / Typecheck / Test

pnpm install
pnpm typecheck
pnpm build
pnpm test

• Run locally (with source maps)

pnpm build && pnpm dev

• Project layout
  • Server & CLI: src/index.ts
  • HTTP client: src/http/client.ts
  • Tool registry: src/tools/registry.ts
  • Built-in tools: src/tools/builtin/*
  • Remote tools: src/tools/remote/tool_exec_api.ts
  • Logging/redaction: src/util/logger.ts, src/util/redact.ts
• Testing notes
  • Tests run with Node’s test runner against compiled artifacts (dist/test/**/*.js). Ensure pnpm build before pnpm test if invoking scripts individually.
• Publishing (optional)
  • The package is published as @discourse/mcp and exposes a bin named discourse-mcp. Prefer npx @discourse/mcp@latest for frictionless usage.
• Conventions
  • Focus on text-oriented outputs; keep embedded JSON concise.
  • Be careful with write operations; keep them opt-in and rate-limited.

For additional guidance on using this server from agent frameworks, see AGENTS.md.

📄 FAQ

• Why is create_post missing? You’re in read-only mode. Enable writes as described above.
• Can I disable remote tool discovery? Yes, run with --tools_mode=discourse_api_only.
• Can I avoid exposing discourse_select_site? Yes, start with --site <url> to tether to a single site.
• Time outs or rate limits? Increase --timeout_ms, and note built-in retry/backoff on 429/5xx.