discourse-mcp

Purpose

discourse-mcp is a Model Context Protocol (MCP) stdio server used to provide the functionality of a Discourse forum to AI agents in the form of tools and resources. It allows AI clients to search forum topics, read posts, manage categories and tags, discover users, and interact with the community.

Main capabilities

• Search topics and posts, with support for selecting the target site via discourse_select_site, or using the --site parameter to bind the server to a single site.
• Read post content, with support for controlling the number of returned characters via --max-read-length (default 50000), and preferentially requesting raw content (include_raw=true).
• Manage categories, groups, and tag groups: category and group resources are retained as compatibility interfaces, while canonical list tools are also provided; tag groups have a dedicated toolset (tag_groups), including six tools for search, list, get, create, update, and delete.
• User discovery and interaction: supports listing users and viewing user information (email can be included via --show_emails, requires admin privileges).
• Write operations: including changes to posts, topics, private messages, categories, users, uploads, drafts, and Data Explorer queries, disabled by default and requiring --allow_writes to enable.
• Built-in Data Explorer toolset: can expose read-only Data Explorer tools for query retrieval and execution.

Usage

Quick start (read-only mode)

In the MCP client, call the discourse_select_site tool and pass { "site": "https://try.discourse.org" } to select a site, or use --site https://try.discourse.org to start the server and bind the site (in this case discourse_select_site is hidden).

Enable writes

Use the --allow_writes flag to enable write tools. Write tools require a matching auth_pairs entry to be configured for the selected site, otherwise an error is returned. Write operations have a rate limit of about 1 request/second.

Authentication

No authentication by default. The following methods are supported:

• Admin API key (requires admin privileges): --auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]'
• User API key (can be generated by any user): --auth_pairs '[{"site":"https://example.com","user_api_key":"...","user_api_client_id":"..."}]'
• HTTP Basic authentication (for sites behind a reverse proxy): add http_basic_user and http_basic_pass to the auth_pairs entry. Multiple auth_pairs entries can be included, and the entry matching the selected site will be used. If both user_api_key and api_key are provided for the same site, user_api_key takes precedence.

Use in an MCP client (e.g. Claude Desktop)

Run via npx. The server registers tools under the MCP server name @discourse/mcp.

Flags and defaults

• --help, -h: print CLI help and exit.
• --version, -v: print the version line and exit.
• --allow_writes (default false): enable mutation tools.
• --read_only <boolean>: deprecated compatibility setting; true conflicts with --allow_writes, false has no effect.
• --timeout_ms <number> (default 15000)
• --concurrency <number> (default 4)
• --log_level <silent|error|info|debug> (default info)
• --show_emails (default false): include emails in user tools, requires admin privileges.
• --tools_mode <auto|discourse_api_only|tool_exec_api> (default auto)
• --toolsets <name[,name...]>: expose selected built-in domains; if omitted, use the compact default catalog.
• --site <url>: bind to a single site and hide discourse_select_site.
• --default-search <prefix>: unconditionally add a prefix to every search query.
• --max-read-length <number>: maximum number of characters returned for post content (default 50000).
• --allowed_upload_paths <paths>: list of directories allowed for local file uploads, requires enabling discourse_upload_file.
• --transport <stdio|http> (default stdio): use standard input/output, or loopback-only Streamable HTTP.
• --port <number> (default 3000): the listening port for HTTP transport.
• --cache_dir <path> (reserved)
• --profile <path.json>: use a configuration file; flags will still override values in the configuration file.

Built-in Toolsets

Toolsets allow operators to expose only the built-in domains needed by the MCP client. When --toolsets and the configuration file field are omitted, the server registers the default catalog (including search, discourse_search, and discourse_filter_topics). Administrative and specialized domains marked as (opt-in) (including themes) must be explicitly selected. Use --toolsets all only when all built-in domains are genuinely needed. Available toolsets include: data_explorer, administration, groups, tag_groups, etc. Toolset selection is separate from security and authorization: the selected toolsets form a union, and read-only mode still removes tools that require writes to be enabled. Toolsets only filter built-in tools; they are not an authorization or complete capability boundary.

Use Cases

• An AI agent needs to interact with a Discourse forum for information retrieval, content reading, or community management.
• Automate community operations tasks, such as batch-managing categories, tag groups, or users.
• Integrate forum functionality into AI workflows through an MCP client (such as Claude Desktop).

Limitations

• Write operations are disabled by default and require explicit enabling and authentication configuration.
• Private message lists and reading require a matching authenticated site, because private message data is never public.
• Write operations have a rate limit of about 1 request/second.
• Toolset selection does not bypass write security; selected write tools remain unavailable when writes are not enabled.
• An unknown or empty toolset selection is a configuration error.
• Local file uploads require --allowed_upload_paths to specify the allowed directories, and these paths do not undergo ~ expansion.
• HTTP transport explicitly supports one stateful MCP client/session per process, with a request body limit of 4 MiB.
• Some features (such as tag group operations) require upstream staff permissions or the tagging_enabled setting.
• Version 0.3.1 simplifies write selection, --allow_writes is sufficient, and deprecates read_only=false; 0.2.x introduced breaking changes from 0.1.x, including JSON-only tool output.