
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 分