Discourse MCP

What the discourse/discourse-mcp MCP server does

The discourse/discourse-mcp MCP server exposes Discourse forum capabilities through the Model Context Protocol. It is distributed as a Node package, uses the MCP SDK, and supports Node.js 24 or newer. The default transport is stdio, which fits desktop MCP clients and local agent processes; a loopback Streamable HTTP mode is also available for a stateful client session.

The server covers common forum investigation tasks. Agents can validate and select a Discourse site, search topics or individual posts, inspect topic metadata and post content, retrieve bounded sections of a topic, and look up users. Additional tools expose user post history, chat-channel messages, private-message mailboxes, drafts, and Data Explorer queries. Private messages require authentication and cannot be read as public topics.

How it works

A site can be selected during execution with discourse_select_site, which validates the target through Discourse’s /about.json endpoint. Alternatively, --site binds the process to one URL and removes the site-selection tool. Search and topic tools return JSON structures with result arrays and pagination metadata. Post-oriented tools preserve matched posts, authors, topics, categories, excerpts, and other evidence instead of reducing results to topic matches.

Topic reading has bounded behavior. A full topic read may make multiple upstream requests when a large post limit is requested. The topic-posts tool supports exact, earliest, latest, around-post, and username-based selection, with a maximum of 50 posts and an indication of the visible stream size. Data Explorer execution is read-only, accepts parameters, returns columns and rows, and has a 10-second query timeout.

The discourse/discourse-mcp MCP server starts without credentials by default, but authenticated site entries can be supplied for API access. It accepts administrator API keys, user API keys, and optional HTTP Basic credentials for sites protected by a reverse proxy. Multiple site entries may be configured, with the entry matching the selected site used for requests.

Setup and configuration

The release package can be started with npx -y @discourse/mcp@latest. An MCP client can launch it as a command, or use the installed discourse-mcp binary. The README gives a Claude Desktop configuration using the npx command. A JSON profile is available when credentials or operational settings should not be placed directly in shell arguments; command-line flags override profile values.

Useful options include --timeout_ms, --concurrency, --log_level, --show_emails, --max-read-length, --default-search, and --toolsets. Toolsets allow an operator to expose selected domains instead of the default catalog. --tools_mode can restrict operation to the Discourse API or select the tool-execution API behavior described by the project.

Writes are disabled unless --allow_writes is supplied. Write-capable domains include posts, topics, private messages, categories, users, uploads, drafts, and saved Data Explorer queries, subject to matching authentication. Write actions are rate-limited to approximately one request per second. Local uploads additionally require an allowed-path configuration.

Tools and capabilities

• Select and validate a Discourse site.
• Search topics or post-level evidence using Discourse query syntax.
• Filter, rank, and inspect topics through filtered, top, or hot views.
• Read complete or bounded topic and post evidence.
• Discover users and list a user’s posts; listing all users requires an admin API key.
• Retrieve chat messages, drafts, private messages, and Data Explorer query details.
• Execute read-only Data Explorer queries with an admin API key.

Limitations and notes

The discourse/discourse-mcp MCP server’s post search is keyword-based, not Discourse AI semantic search. The “hot” topic view is defined as daily top, not sentiment, controversy, or real-time activity. Admin API keys are required for user-directory listing, Data Explorer query inspection, and query execution. Showing email addresses requires admin access and the relevant option.

Private-message tools require a matching authenticated site because private-message data is never public. HTTP transport supports one stateful MCP client session per process; a new process is required after that session is closed. The deprecated --read_only=false setting should not be used; --allow_writes is the current write opt-in.