
Discourse Mcp Extended
io.github.devzspy由 GitHub 帳號 devzspy 發布v0.1.0更新於 Oct 25, 2026
Discourse MCP server (stdio) with review-queue tools added. Fork of @discourse/mcp.
概覽
一個本機 stdio MCP 伺服器,將 Discourse 論壇功能開放給 AI 助理,並新增列出與處理審核佇列的工具。
- 可以做什麼
- 搜尋與篩選主題,以 JSON 讀取主題與貼文,可設定內容長度上限與搜尋前綴。查詢使用者、列出使用者貼文,管理員可列出使用者。讀取聊天頻道與訊息,讀取、儲存與刪除草稿。以唯讀資源瀏覽分類、標籤、群組與聊天頻道。處理審核佇列:列出待審或被檢舉項目,並在啟用寫入後核准、拒絕或執行其他操作。僅在明確啟用寫入時,建立與更新貼文、主題、分類、使用者,以及上傳檔案。
- 適用情境
- 適合讓助理參與 Discourse 論壇工作:搜尋與摘要討論、起草或發佈貼文與主題,或協助版主處理審核佇列。建議先以唯讀方式使用,僅在信任助理變更內容的網站上啟用寫入。
- 執行需求
- 以本機 Node.js 程序執行(需 Node 24 或更新版本);清單列出 npm 套件,但 README 說明此分支未發佈到 npm,需用 pnpm 在本機建置。需要能連線目標 Discourse 網站的網路。驗證為選用:管理員 API 金鑰(api_key 加 api_username)或使用者 API 金鑰(user_api_key,可選 user_api_client_id),透過 auth_pairs 或設定檔傳入;受反向代理保護的網站可加上 HTTP Basic 憑證。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Discourse Mcp Extended,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
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
來源:README.md,提交 189bbc7
工具
0版本歷史
1- v0.1.0最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分