Provides comprehensive tools for interacting with Discourse forum platforms, including searching posts, reading topics and posts, managing categories and tags, retrieving user information, filtering topics with advanced query syntax, and creating posts/categories when write permissions are enabled.
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 todist/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 casediscourse_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
.
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 hidesdiscourse_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
anddiscourse.create_category
are only registered when all are true:--allow_writes
AND not--read_only
AND some auth is configured (either default flags or a matchingauth_pairs
entry).
- A ~1 req/sec rate limit is enforced for
create_post
andcreate_category
.
- 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 hidediscourse_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 todiscourse_read_post
and per-post content indiscourse_read_topic
. The tools preferraw
content by requestinginclude_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) ortool_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.
- 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.
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:
- Input:
discourse_read_topic
- Input:
{ topic_id: number; post_limit?: number (1–20, default 5) }
- Input:
discourse_read_post
- Input:
{ post_id: number }
- Input:
discourse_list_categories
- Input:
{}
- Input:
discourse_list_tags
- Input:
{}
- Input:
discourse_get_user
- Input:
{ username: string }
- Input:
discourse_filter_topics
- Input:
{ filter: string; page?: number (default 1); per_page?: number (1–50) }
- Query language (succinct): key 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-DD
or 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_create_post
(only when writes enabled; see Write safety)- Input:
{ topic_id: number; raw: string (≤ 30k chars) }
- 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 }
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
- Server & CLI:
- Testing notes
- Tests run with Node’s test runner against compiled artifacts (
dist/test/**/*.js
). Ensurepnpm build
beforepnpm test
if invoking scripts individually.
- Tests run with Node’s test runner against compiled artifacts (
- Publishing (optional)
- The package is published as
@discourse/mcp
and exposes abin
nameddiscourse-mcp
. Prefernpx @discourse/mcp@latest
for frictionless usage.
- The package is published as
- 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):
FAQ
- Why is
create_post
missing? 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.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables AI agents to interact with Discourse forums through search, reading topics/posts, managing categories and users. Supports secure authentication and optional write operations with rate limiting.
Related MCP Servers
- -securityFlicense-qualityEnables searching for AI agents by keywords or categories, allowing users to discover tools like coding agents, GUI agents, or industry-specific assistants across marketplaces.Last updated -37
- AsecurityAlicenseAqualityEnables AI assistants to interact with WordPress sites through REST APIs, allowing programmatic management of posts, users, comments, categories, and tags with secure authentication.Last updated -2943MIT License
- -securityFlicense-qualityProvides social media functionality for AI agents, enabling them to login with unique handles, read filtered posts, and create posts or replies within team-based discussions.Last updated -3
- AsecurityAlicenseAqualityEnables AI agents to interact with Notion workspaces through the Notion API. Supports reading, writing, commenting, and managing Notion pages and databases with optimized token consumption for AI agents.Last updated -1946,432MIT License