
Discourse Mcp Extended
io.github.devzspyPublished by GitHub account devzspyv0.1.0Updated Oct 25, 2026
Discourse MCP server (stdio) with review-queue tools added. Fork of @discourse/mcp.
Overview
A local stdio MCP server that exposes Discourse forum capabilities to an AI assistant, with added tools for listing and acting on the moderation review queue.
- What you can do
- Search and filter topics, and read topics and posts as JSON with configurable length limits and search prefixes. Look up users and list their posts, and list users for admins. Read chat channels and messages, and read, save or delete drafts. Browse categories, tags, groups and chat channels as read-only resources. Moderate the review queue: list pending or flagged items and approve, reject or otherwise act on them when writes are enabled. Create and update posts, topics, categories and users, and upload files, only when writes are explicitly enabled.
- When to use it
- Useful when an assistant should work with a Discourse forum: searching and summarizing discussions, drafting or publishing posts and topics, or helping moderators triage the review queue. Start read-only and enable writes only for sites where the assistant is trusted to change content.
- Requirements
- Runs as a local Node.js process (Node 24 or newer); the manifest lists an npm package, though the README says this fork is not published to npm and must be built locally with pnpm. Needs network access to the target Discourse site. Authentication is optional: admin API keys (api_key plus api_username) or user API keys (user_api_key, optional user_api_client_id), passed via auth_pairs or a profile file; HTTP Basic credentials can be added for proxied sites.
Installation
In SourceWeft
- Open Discourse Mcp Extended in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
Discourse MCP (extended fork)
This is a fork of 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 todist/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)
Then, in your MCP client, either:
-
Call the
discourse_select_sitetool 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 casediscourse_select_siteis 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.
Configuration
The server registers tools under the MCP server name @discourse/mcp. Choose a target Discourse site either by:
-
Using the
discourse_select_sitetool at runtime (validates via/about.json), or -
Supplying
--site <url>to tether the server to a single site at startup (validates via/about.jsonand hidesdiscourse_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_userandhttp_basic_passto anyauth_pairsentry. 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 bothuser_api_keyandapi_keyare provided for the same site,user_api_keytakes 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_writesAND not--read_only. - Write tools require a matching
auth_pairsentry 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 <number>(default: 15000)--concurrency <number>(default: 4)--log_level <silent|error|info|debug>(default: info)debug: Shows all HTTP requests, responses, and detailed error informationinfo: Shows retry attempts and general operational messageserror: Shows only errorssilent: 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)--site <url>: Tether MCP to a single site and hidediscourse_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 todiscourse_read_postand per-post content indiscourse_read_topic. The tools preferrawcontent by requestinginclude_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 indiscourse_upload_file. Example:--allowed_upload_paths "/home/user/images,/tmp/uploads"or--allowed_upload_paths '["/home/user/images"]'--transport <stdio|http>(default: stdio): Transport type. Usestdiofor standard input/output (default), orhttpfor 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)
Run with:
Flags still override values from the profile.
-
Remote Tool Execution API (optional)
- With
tools_mode=auto(default) ortool_exec_api, the server discovers remote tools via GET/ai/toolsafter you select a site (or immediately at startup if--siteis provided) and registers them dynamically. Set--tools_mode=discourse_api_onlyto disable remote tool discovery.
- With
-
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} } permsis array of{gid, perm}where perm: 1=full, 2=create_post, 3=readonly- Note:
permsis only populated with admin/moderator auth. Without admin auth, onlyread_restrictedboolean 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
gidvalues 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} }
- Input:
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 }
- Input:
discourse_read_post- Input:
{ post_id: number } - Output:
{ id, topic_id, topic_slug, post_number, username, created_at, raw, truncated }
- Input:
discourse_get_user- Input:
{ username: string } - Output:
{ id, username, name, trust_level, created_at, bio, admin, moderator }
- Input:
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} }
- Input:
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); personalin:(bookmarked|watching|tracking|muted|pinned); dates: created/activity/latest-post-(before|after) withYYYY-MM-DDor relative daysN; 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.
- Input:
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 }
- Input:
discourse_get_draft- Input:
{ draft_key: string; sequence?: number } - Output:
{ draft_key, sequence, found, data: {title, reply, category_id, tags, action} }
- Input:
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:
{ reviewables: [{id, type, status, score, created_at, topic_id, category_id, post_id, target_user_id, created_by, target_created_by, title, excerpt, version, actions}], meta: {page, limit, total, has_more} } - Lists items from the review queue (as seen at
/review?sort_order=score), including new/queued posts awaiting approval and flagged posts.actionsis the list of valid action ids for that item (e.g.approve_post,reject_post,agree_and_hide,disagree,delete) to pass todiscourse_perform_reviewable_action. 10 items per page (Discourse's fixed page size).
- Input:
discourse_perform_reviewable_action(only when writes enabled; see Write safety)- Input:
{ reviewable_id: number; action_id: string; version: number; reject_reason?: string; revise_feedback?: string } - Output:
{ success, reviewable_id, action_id, version, created_post_id, created_post_topic_id, reviewable_updates } - Approves, rejects, or otherwise acts on a review queue item. Use
discourse_list_reviewablesfirst to get thereviewable_id, currentversion, and validaction_idvalues for that specific item.
- Input:
discourse_save_draft(only when writes enabled; see Write safety)- Input:
{ draft_key: string; reply: string; title?: string; category_id?: number; tags?: string[]; sequence?: number (default 0); action?: "createTopic" | "reply" | "edit" | "privateMessage" } - Output:
{ draft_key, sequence, saved }
- Input:
discourse_delete_draft(only when writes enabled; see Write safety)- Input:
{ draft_key: string; sequence: number } - Output:
{ draft_key, deleted }
- Input:
discourse_create_post(only when writes enabled; see Write safety)- Input:
{ topic_id: number; raw: string (<= 30k chars); author_username?: string } - Output:
{ id, topic_id, post_number }
- Input:
discourse_create_topic(only when writes enabled; see Write safety)- Input:
{ title: string; raw: string (<= 30k chars); category_id?: number; tags?: string[]; author_username?: string } - Output:
{ id, topic_id, slug, title }
- Input:
discourse_update_topic(only when writes enabled; see Write safety)- Input:
{ topic_id: number; title?: string; category_id?: number; tags?: string[]; featured_link?: string; original_title?: string; original_tags?: string[] } - Output:
{ success, topic_id, updated_fields, topic: {id, title, slug, category_id, tags, featured_link} }
- Input:
discourse_list_users(requires admin API key)- Input:
{ query?: "active"|"new"|"staff"|"suspended"|"silenced"|"pending"|"staged"; filter?: string; order?: "created"|"last_emailed"|"seen"|"username"|"trust_level"|"days_visited"|"posts"; asc?: boolean; page?: number } - Output:
{ users: [{id, username, name, email, avatar_template, trust_level, created_at, last_seen_at, admin, moderator, suspended, silenced}], meta: {page, has_more} } - Note: Returns ~100 users per page (Discourse's fixed page size).
avatar_templatecontains{size}placeholder - replace with pixel size (e.g., 120) to get avatar URL
- Input:
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; upload_id?: number } - Output:
{ success, username, name, email, active, avatar_updated, message, avatar_error? } - Note: If
upload_idis provided but avatar update fails,avatar_errorcontains the error message
- Input:
discourse_update_user(only when writes enabled; see Write safety)- Input:
{ username: string; name?: string; bio_raw?: string; location?: string; website?: string; title?: string; date_of_birth?: string; locale?: string; profile_background_upload_url?: string; card_background_upload_url?: string; upload_id?: number } - Output:
{ success, username, updated_fields, avatar_updated, user: {...}, avatar_error? } - Note: If
upload_idis provided but avatar update fails,avatar_errorcontains the error message
- Input:
discourse_upload_file(only when writes enabled; see Write safety)- Input:
{ upload_type: "avatar"|"profile_background"|"card_background"|"composer"; image_data?: string (base64); url?: string; filename?: string; user_id?: number } - Output:
{ id, url, short_url, short_path, original_filename, extension, width, height, filesize, human_filesize } - Constraints:
- Provide exactly one of:
image_data(requiresfilename), remote HTTP(S) URL, or absolute local file path user_idis required for avatar/profile_background/card_background uploads- Local file uploads require
--allowed_upload_pathsconfiguration (security: prevents arbitrary file reads)
- Provide exactly one of:
- Note: Use
short_url(e.g.,upload://abc123.png) to embed images in posts.
- Input:
discourse_create_category(only when writes enabled; see Write safety)- Input:
{ name: string; color?: hex; text_color?: hex; emoji?: string; icon?: string; parent_category_id?: number; description?: string } - Output:
{ id, slug, name }
- Input:
discourse_select_site(hidden when--siteis provided)- Input:
{ site: string } - Output:
{ site, title }
- Input:
Development
-
Requirements: Node >= 24,
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 - Resource registry:
src/resources/registry.ts - Built‑in tools:
src/tools/builtin/* - Remote tools:
src/tools/remote/tool_exec_api.ts - JSON helpers:
src/util/json_response.ts - Logging/redaction:
src/util/logger.ts,src/util/redact.ts
- Server & CLI:
-
Testing notes
- Tests run with Node’s test runner against compiled artifacts (
dist/test/**/*.js). Ensurepnpm buildbeforepnpm testif invoking scripts individually.
- Tests run with Node’s test runner against compiled artifacts (
-
Publishing (optional)
- The package is published as
@discourse/mcpand exposes abinnameddiscourse-mcp. Prefernpx @discourse/mcp@latestfor frictionless usage.
- The package is published as
-
Conventions
- All outputs are JSON-only for reliable programmatic parsing by agents.
- 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
Quick Start with User API Key (No Admin Required)
Other Examples
- Read‑only session against
try.discourse.org:
- Tether to a single site:
- Create a post with Admin API Key (writes enabled):
- Create a post with User API Key (writes enabled, no admin required):
- Create a category (writes enabled):
- Create a topic (writes enabled):
- Run with HTTP transport (on port 3000):
- Connect to a site behind HTTP Basic Auth:
Authentication
Admin API Keys vs User API Keys
This MCP server supports two types of Discourse API authentication:
-
Admin API Keys (
api_key+api_username)- Require admin/moderator permissions to generate
- Created via Admin Panel → API → New API Key
- Can perform all operations including user/category creation
- Use headers:
Api-KeyandApi-Username
-
User API Keys (
user_api_key+ optionaluser_api_client_id)- Can be generated by any user (no admin required)
- User-specific permissions and rate limits
- Ideal for personal use and non-admin operations
- Use headers:
User-Api-KeyandUser-Api-Client-Id - Auto-expire after 180 days of inactivity (configurable per site)
- Learn more: https://meta.discourse.org/t/user-api-keys-specification/48536
Obtaining a User API Key
Easy Method: Built-in Generator (Recommended)
This package includes a convenient command to generate User API Keys:
The command will:
- Generate an RSA key pair
- Display an authorization URL for you to visit
- Prompt you to paste the encrypted payload after authorization
- Decrypt and display your User API Key
- Optionally save it to a profile file
Manual Method
User API Keys require an OAuth-like flow documented at https://meta.discourse.org/t/user-api-keys-specification/48536. Key steps:
- Generate a public/private key pair
- Request authorization via
/user-api-key/newwith your public key, application name, client ID, and requested scopes - User approves the request (after login if needed)
- Discourse returns an encrypted payload with the User API Key
- Decrypt using your private key and use the key in your configuration
You can also manually create User API Keys via the Discourse UI (if enabled by the site):
- Visit your user preferences → Security → API
- Or use third-party tools that implement the User API Key flow
FAQ
- Why is
create_postmissing? 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. - Should I use Admin API Keys or User API Keys? Use User API Keys for personal use (no admin required). Use Admin API Keys only when you need admin-level operations or are setting up a system-wide integration.
- Getting "fetch failed" errors? Run with
--log_level debugto see detailed error information including:- The exact URL being requested
- HTTP status codes and response bodies
- Network-level errors (DNS, SSL/TLS, connectivity issues)
- Retry attempts and timing
- Timeout diagnostics
Source: README.md at commit 189bbc7
Tools
0Version history
1- v0.1.0LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts