Discourse

You can run a Discourse MCP server locally to access Discourse forum capabilities as programmable tools for AI agents. This server supports read‑only by default, with optional guarded write operations, and can be tethered to a specific site or discover sites at runtime. It exposes a practical set of tools for searching, reading, drafting, and managing topics, posts, categories, and users within Discourse.

How to use

Start with a read‑only setup to explore the available tools and confirm connectivity to a Discourse site. You can tether to a single site at startup or select a site at runtime. Writes are opt‑in and rate limited, so begin by enumerating data and building confidence before enabling any modifications.

To use the server with an MCP client, run it through the standard MCP command path and connect your client to the server. You can either launch the server from an inline command (via npx) or install a global binary and invoke it directly. When you start the server, you can choose a site or let the client select one. If you start with a specific site using a startup flag, the site selector is hidden and all calls target that site.

From your MCP client, call tools such as discourse_search to locate topics, discourse_read_topic to examine topic contents, or discourse_read_post to fetch individual posts. If you need drafts, you can work with discourse_list_drafts, discourse_get_draft, and other read‑only tooling. When you are ready to write, enable writes and provide appropriate authentication so you can create posts, topics, categories, or users.

How to install

Prerequisites you need before getting started:

• Node.js version 18 or newer is required
• pnpm is recommended for installation and build

Install the package and run the server in a read‑only mode first to verify connectivity and tool availability.

pnpm install -g @discourse/mcp
npx @discourse/mcp@latest

Configuration and startup options

The server exposes tools under the MCP server name corresponding to the package. You can either select a site at runtime or tether to a single site at startup. Writes are disabled by default and become enabled only when you provide proper authentication and the --allow_writes flag.

Common startup patterns include using npx for quick experiments or running a global binary if you prefer a persistent command.

Key startup options to be aware of include:

• --read_only: default true
• --allow_writes: default false
• --site <url>: tether to a single site and hide discourse_select_site
• --auth_pairs: provide admin or user API keys for write operations
• --timeout_ms: request timeout in milliseconds (default 15000)
• --log_level: silent|error|info|debug (default info)
• --port: port when using HTTP transport (default 3000)
• --transport: stdio|http (default stdio)
• --default-search: prefix all searches (e.g., tag:ai order:latest)
• --max-read-length: max characters returned for read content (default 50000)
• --profile: path to a JSON profile file (overrides flags)

If you want the server to connect to a site at startup, you can pass --site <url> and the discourse_select_site tool will be hidden. If you prefer dynamic site selection, omit --site and call discourse_select_site after startup.

Using the built‑in example configurations

You can run the MCP server with the built‑in quick start patterns. The following commands demonstrate read‑only startup and a write‑enabled startup using an API key.

# Read‑only start (recommended to begin)
npx -y @discourse/mcp@latest

# Enable writes (opt‑in, safe guarded)
npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"<REDACTED>","api_username":"system"}]'

Available tools

discourse_search

Searches Discourse for topics matching a query and returns a text summary with a compact JSON footer containing results.

discourse_read_topic

Reads the content of a topic by its ID, with an optional limit on the number of posts returned.

discourse_read_post

Fetches a single post by its post_id.

discourse_list_categories

Lists all categories available in the current site.

discourse_list_tags

Lists all tags used across topics.

discourse_get_user

Retrieves user information for a given username.

discourse_filter_topics

Filters topics based on complex criteria including tags, status, and date ranges.

discourse_list_chat_channels

Lists public chat channels visible to the authenticated user.

discourse_list_user_chat_channels

Lists chat channels for the current user, including direct messages and membership information.

discourse_get_draft

Retrieves a draft by its key and optional sequence.

discourse_list_drafts

Lists all drafts for the current user with preview content.

discourse_save_draft

Saves or updates a draft for a new topic, reply, or private message when writes are enabled.

discourse_delete_draft

Deletes a draft by its key and sequence number.

discourse_create_post

Creates a new post in an existing topic with the provided raw content.

discourse_create_topic

Creates a new topic with a title, raw content, and optional category and tags.

discourse_create_user

Creates a new Discourse user with username, email, and profile details when allowed by permissions.

discourse_create_category

Creates a new category with name and optional color, hierarchy, and description.