discourse-mcp

## Discourse MCP

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 to `dist/index.js` (binary name: `discourse-mcp`)
- **SDK**: `@modelcontextprotocol/sdk`
- **Node**: >= 24
- **Version**: 0.3.1 (simplifies write opt-in so `--allow_writes` is sufficient and deprecates `read_only=false`; 0.3.0 added operator-selectable toolsets, structured directory output, and expanded opt-in administration capabilities; 0.2.x introduced breaking changes from 0.1.x, including JSON-only tool output; category/group resources remain deprecated compatibility surfaces alongside canonical list tools)

### Quick start (release)

- **Run (read‑only, recommended to start)**

```bash
npx -y @discourse/mcp@latest
```

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 case `discourse_select_site` is hidden).

- **Enable writes (opt‑in, safe‑guarded)**

```bash
npx -y @discourse/mcp@latest --allow_writes --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'
```

- **Run with only Data Explorer built-in tools**

```bash
npx -y @discourse/mcp@latest --toolsets data_explorer --tools_mode discourse_api_only
```

This exposes `discourse_select_site` plus the read-only Data Explorer tools. Add `--site`, authentication, and the write flags as needed; see [Built-in toolsets](#built-in-toolsets).

- **Use in an MCP client (example: Claude Desktop) — via npx**

```json
{
  "mcpServers": {
    "discourse": {
      "command": "npx",
      "args": ["-y", "@discourse/mcp@latest"],
      "env": {}
    }
  }
}
```

> Alternative: if you prefer a global binary after install, the package exposes `discourse-mcp`.
>
> ```json
> {
>   "mcpServers": {
>     "discourse": { "command": "discourse-mcp", "args": [] }
>   }
> }
> ```

## 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 hides `discourse_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_user` and `http_basic_pass` to any `auth_pairs` entry. 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 both `user_api_key` and `api_key` are provided for the same site, `user_api_key` takes precedence.

- **Write safety**

  - Writes are disabled by default.
  - Built-in write tools are only registered when `--allow_writes` is enabled. This includes post, topic, private-message, category, user, upload, draft, and saved Data Explorer query mutations.
  - Private-message listing and reading also require a matching authenticated site because PM data is never public.
  - Toolset selection does not bypass write safety. A selected write tool remains absent unless writes are enabled.
  - Write tools require a matching `auth_pairs` entry for the selected site; otherwise they return an error.
  - A ~1 req/sec rate limit is enforced for write actions.

- **Flags & defaults**

  - `--help`, `-h`, or positional `help`: print current CLI help and exit successfully before loading profiles or starting a transport.
  - `--version`, `-v`, or positional `version`: print one package-version line and exit successfully. `-v` means version; logging verbosity uses `--log_level`.

  - `--allow_writes` (default: false): enable mutation tools. This single explicit opt-in is sufficient.
  - `--read_only <boolean>`: deprecated compatibility setting. `true` is an explicit read-only override and conflicts with `--allow_writes`; `false` has no effect and should be removed from commands and profiles.
  - `--timeout_ms <number>` (default: 15000)
  - `--concurrency <number>` (default: 4)
  - `--log_level <silent|error|info|debug>` (default: info)
    - `debug`: Shows HTTP request URLs, statuses, and detailed network/retry information (response bodies are never logged because admin APIs may echo sensitive content)
    - `info`: Shows retry attempts and general operational messages
    - `error`: Shows only errors
    - `silent`: 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)
  - `--toolsets <name[,name...]>`: Expose selected built-in domains. Omit for the compact default catalog (all non-opt-in domains); use `--toolsets all` to include opt-in category/group/tag-group, moderation, workflow, and AI administration domains. See [Built-in toolsets](#built-in-toolsets).
  - `--site <url>`: Tether MCP to a single site and hide `discourse_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 to `discourse_read_post` and per-post content in `discourse_read_topic` and `discourse_read_private_message`. The tools prefer `raw` content by requesting `include_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 in `discourse_upload_file`. Example: `--allowed_upload_paths "/home/user/images,/tmp/uploads"` or `--allowed_upload_paths '["/home/user/images"]'`. These security-sensitive paths do **not** receive `~` expansion.
  - `--transport <stdio|http>` (default: stdio): Use standard input/output by default, or loopback-only Streamable HTTP with JSON responses. HTTP explicitly supports one stateful MCP client/session per process. Every post-initialize request must carry the returned `Mcp-Session-Id`; a second initialize is rejected. After session DELETE/close, restart the process before connecting another client. `/health` returns `503 restart_required` in that closed state. Request bodies are bounded to 4 MiB.
  - `--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)

```json
{
  "auth_pairs": [
    {
      "site": "https://try.discourse.org",
      "api_key": "<redacted>",
      "api_username": "system"
    },
    {
      "site": "https://example.com",
      "user_api_key": "<user_api_key>",
      "user_api_client_id": "<client_id>"
    },
    {
      "site": "https://protected.example.com",
      "api_key": "<redacted>",
      "api_username": "system",
      "http_basic_user": "username",
      "http_basic_pass": "password"
    }
  ],
  "allow_writes": true,
  "show_emails": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org",
  "default_search": "tag:ai order:latest",
  "max_read_length": 50000,
  "transport": "stdio",
  "port": 3000,
  "allowed_upload_paths": ["/home/user/images", "/tmp/uploads"]
}
```

Run with:

```bash
node dist/index.js --profile /absolute/path/to/profile.json
# Current-user home expansion is also supported:
node dist/index.js --profile ~/discourse-mcp-profile.json
```

Flags still override values from the profile. A leading current-user `~`, `~/`, or `~\` in the **profile path** expands to the current home directory; `~otheruser`, shell-style expansion elsewhere, and upload-allowlist expansion are intentionally unsupported.

### Built-in toolsets

Toolsets let an operator expose only the built-in domains needed by an MCP client. They are optional: when `--toolsets` and the profile field are both omitted, the server registers the default catalog (including `search`, `discourse_search`, and `discourse_filter_topics`). Administrative and specialized domains marked *(opt-in)* below—including `themes`—must be selected explicitly. Use `--toolsets all` only when every built-in domain is deliberately required.

Pass one name or a comma-separated union:

```bash
# Data Explorer reads, plus the site-selection bootstrap tool
npx -y @discourse/mcp@latest \
  --toolsets data_explorer \
  --tools_mode discourse_api_only

# Search and topic tools, retaining canonical registration order
npx -y @discourse/mcp@latest \
  --toolsets search,topics \
  --tools_mode discourse_api_only

# Every built-in domain, including opt-in workflows
npx -y @discourse/mcp@latest \
  --toolsets all \
  --tools_mode discourse_api_only

# Author, test, and run workflows (admin key required)
npx -y @discourse/mcp@latest \
  --toolsets workflows \
  --site https://forum.example.com \
  --auth_pairs '[{"site":"https://forum.example.com","api_key":"...","api_username":"system"}]' \
  --allow_writes \
  --tools_mode discourse_api_only
```

Profiles use an array (a comma-separated string is also accepted):

```json
{
  "toolsets": ["users", "uploads"]
}
```

Available toolsets are:

| Toolset | Built-in tools |
|---|---|
| `site` | `discourse_select_site` (also retained implicitly as bootstrap for any untethered subset) |
| `search` | Topic-level search/filtering plus post-level keyword evidence |
| `topics` | Core topic/post reads, exact stream selection, post search, user-post activity, and mutations |
| `users` | User lookup/listi