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

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

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.

  • --auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]': Per‑site API key overrides. You can include multiple entries; the matching entry is used for the selected site.

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

  • --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 (keep secrets off the command line)

Run with:

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

• discourse_create_topic (only when writes enabled; see Write safety)

  • Input: { title: string; raw: string (≤ 30k chars); category_id?: number; tags?: string[] }

• discourse_create_user (only when writes enabled; see Write safety)

• Input: { username: string (1-20 chars); email: string; name: string; password: string; active?: boolean; approved?: boolean }

• discourse_create_category (only when writes enabled; see Write safety)

• Input: { name: string; color?: hex; text_color?: hex; parent_category_id?: number; description?: string }

Notes:

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

Development

• Requirements: Node >= 18, pnpm.

• Install / Build / Typecheck / Test

• Run locally (with source maps)

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

See AGENTS.md for additional guidance on using this server from agent frameworks.

Examples

• Read‑only session against try.discourse.org:

• Tether to a single site:

• Create a post (writes enabled):

• Create a category (writes enabled):

• Create a topic (writes enabled):

FAQ

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