Discourse MCP Extended

Discourse MCP (extended fork)

This is a fork of [discourse/discourse-mcp](https://github.com/discourse/discourse-mcp), extended with tools for working the Discourse review queue (/review) — listing pending/flagged items and approving or rejecting them. Everything else is unchanged from upstream. See What's added in this fork below.

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.2.4 (0.2.x has breaking changes from 0.1.x - JSON-only output, resources replace list tools)

What's added in this fork

• `discourse_list_reviewables` — list items in the review queue (as seen at /review?sort_order=score), e.g. new/queued posts awaiting approval and flagged posts. Requires an admin or moderator API key/user API key for the site.
• `discourse_perform_reviewable_action` — approve, reject, or otherwise act on a review queue item (only registered when writes are enabled, same as other write tools).

Full input/output details are in the Tools section below. Since this build isn't published to npm, run it locally from a build of this repo (pnpm install && pnpm build, then point your MCP client at dist/index.js) instead of npx @discourse/mcp@latest.

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

`json

{

"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 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.
• Write tools (discourse_create_post, discourse_create_topic, discourse_create_category, discourse_update_topic, discourse_create_user, discourse_update_user, discourse_upload_file, discourse_save_draft, discourse_delete_draft, discourse_perform_reviewable_action) are only registered when --allow_writes AND not --read_only.
• 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

• --read_only (default: true)
• --allow_writes (default: false)
• --timeout_ms (default: 15000)
• --concurrency (default: 4)
• --log_level (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
• --show_emails (default: false). includes emails in user tools. Requires admin access
• --tools_mode (default: auto)
• --site : Tether MCP to a single site and hide discourse_select_site.
• --default-search : Unconditionally prefix every search query (e.g., tag:ai order:latest).
• --max-read-length : 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.
• --allowed_upload_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"]'
• --transport (default: stdio): Transport type. Use stdio for standard input/output (default), or http for Streamable HTTP transport (stateless mode with JSON responses).
• --port (default: 3000): Port to listen on when using HTTP transport.
• --cache_dir (reserved)
• --profile (see below)

• Profile file (keep secrets off the command line)

{

"auth_pairs": [ { "site": "https://try.discourse.org", "api_key": " ", "api_username": "system" }, { "site": "https://example.com", "user_api_key": " ", "user_api_client_id": " " }, { "site": "https://protected.example.com", "api_key": " ", "api_username": "system", "http_basic_user": "username", "http_basic_pass": "password" } ], "read_only": false, "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

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.

MCP Resources

Resources provide static/semi-static read-only data via URI addressing. Use these instead of tools for listing operations.

• discourse://site/categories

• List all categories with hierarchy and permissions
• Output: { categories: [{id, name, slug, pid, read_restricted, topic_count, post_count, perms}], meta: {total} }
• perms is array of {gid, perm} where perm: 1=full, 2=create_post, 3=readonly
• Note: perms is only populated with admin/moderator auth. Without admin auth, only read_restricted boolean is available.

• discourse://site/tags

• List all tags with usage counts
• Output: { tags: [{id, name, count}], meta: {total} }

• discourse://site/groups

• List all groups with visibility, interaction levels, and access settings
• Output: { groups: [{id, name, automatic, user_count, vis, members_vis, mention, msg, public_admission, public_exit, allow_membership_requests}], meta: {total} }
• Levels (0-4): 0=public, 1=logged_on_users, 2=members, 3=staff, 4=owners
• Use case: Resolve gid values from category permissions to group names, replicate group settings during migrations

• discourse://chat/channels

• List all public chat channels
• Output: { channels: [{id, title, slug, status, members_count, description}], meta: {total} }

• discourse://user/chat-channels

• List user's chat channels (public + DMs) with unread/mention counts
• Output: { public_channels: [...], dm_channels: [...], meta: {total} }
• Requires authentication

• discourse://user/drafts
• List user's drafts
• Output: { drafts: [{draft_key, sequence, title, category_id, created_at, reply_preview}], meta: {total} }
• Requires authentication

Tools

Built‑in tools (always present unless noted). All tools return strict JSON (no Markdown).

• discourse_search
• Input: { query: string; max_results?: number (1–50, default 10) }
• Output: { results: [{id, slug, title}], meta: {total, has_more} }
• discourse_read_topic
• Input: { topic_id: number; post_limit?: number (1–50, default 5); start_post_number?: number }
• Output: { id, title, slug, category_id, tags, posts_count, posts: [{id, post_number, username, created_at, raw}], meta }
• discourse_read_post
• Input: { post_id: number }
• Output: { id, topic_id, topic_slug, post_number, username, created_at, raw, truncated }
• discourse_get_user
• Input: { username: string }
• Output: { id, username, name, trust_level, created_at, bio, admin, moderator }
• discourse_list_user_posts
• Input: { username: string; page?: number (0-based); limit?: number (1–50, default 30) }
• Output: { posts: [{id, topic_id, post_number, slug, title, created_at, excerpt, category_id}], meta: {page, limit, has_more} }
• discourse_filter_topics
• Input: { filter: string; page?: number; per_page?: number (1–50) }
• Output: { results: [{id, slug, title}], meta: {page, limit, has_more} }
• 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_get_chat_messages
• Input: { channel_id: number; page_size?: number (1–50, default 50); target_message_id?: number; direction?: "past" | "future"; target_date?: string (ISO 8601) }
• Output: { channel_id, messages: [{id, username, created_at, message, edited, thread_id, in_reply_to_id}], meta }
• discourse_get_draft
• Input: { draft_key: string; sequence?: number }
• Output: { draft_key, sequence, found, data: {title, reply, category_id, tags, action} }
• discourse_list_reviewables (requires admin/moderator API key)
• Input: { status?: "pending"|"approved"|"rejected"|"ignored"|"deleted"|"reviewed"|"all"; type?: string; priority?: "low"|"medium"|"high"; sort_order?: "score"|"score_asc"|"created_at"|"created_at_asc"; category_id?: number; topic_id?: number; page?: number }
• Output: `{ reviewabl