discourse-mcp (Cloudflare-friendly fork)

Fork of the official discourse/discourse-mcp that routes Discourse API traffic through impers (curl-impersonate / curl_cffi-style TLS fingerprints).

Use this when the target forum sits behind Cloudflare (or similar) and the stock MCP gets 403 Just a moment... from Node's native fetch.

Requires Node.js >= 24.

Install in Grok Build

1. Profile (auth)

Create ~/.grok/discourse-profile.json (example for a User API key):

{
  "site": "https://www.example.com/",
  "impersonate": "chrome120",
  "auth_pairs": [
    {
      "site": "https://www.example.com/",
      "user_api_key": "YOUR_USER_API_KEY",
      "user_api_client_id": "discourse-mcp"
    }
  ],
  "read_only": false,
  "allow_writes": true,
  "log_level": "info",
  "rate_limit_max": 15,
  "rate_limit_window_ms": 60000,
  "rate_limit_min_interval_ms": 200
}

HTTP sliding-window rate limit

Measured on uscardforum (Cloudflare / edge):

So the dominant pattern is ~20 requests per rolling ~60s window, not a fixed RPS ceiling. Client-side limit should be a sliding window.

Profile / CLI:

uscardforum-safe defaults used locally: 15 / 60s + 200ms min interval (margin under the ~20 hard edge).

Cross-process / all clients: when rate limiting is enabled, timestamps are stored under a shared cache directory (not ~/.grok):

Override with profile rate_limit_state_dir or env DISCOURSE_MCP_RATE_LIMIT_DIR.
One file per site origin (sha1(origin).json) + .lock. Multiple Grok/Claude/Cursor MCP processes share the same window. If the file lock fails, the process falls back to in-memory limiting and logs an error.

Generate a User API key (no admin required):

npx -y github:Sakura-Byte/discourse-mcp generate-user-api-key \
  --site https://www.example.com/ \
  --save-to ~/.grok/discourse-profile.json

2. ~/.grok/config.toml

[mcp_servers.discourse]
command = "npx"
args = [
  "-y",
  "github:Sakura-Byte/discourse-mcp",
  "--profile",
  "/Users/YOU/.grok/discourse-profile.json",
]
enabled = true
startup_timeout_sec = 120

First launch may download npm deps and libcurl-impersonate (or use gh if GitHub API is rate-limited). Prefer a longer startup_timeout_sec.

3. Refresh MCP

• New Grok session, or /mcps → r refresh

• Check: grok mcp doctor discourse

Related MCP server: USCardForum MCP Server

Install in other MCP clients

Claude Desktop / Cursor-style JSON

{
  "mcpServers": {
    "discourse": {
      "command": "npx",
      "args": [
        "-y",
        "github:Sakura-Byte/discourse-mcp",
        "--profile",
        "/absolute/path/to/profile.json"
      ]
    }
  }
}

Local clone

git clone https://github.com/Sakura-Byte/discourse-mcp.git
cd discourse-mcp
npm install   # runs prepare → tsc build
node dist/index.js --profile /path/to/profile.json

Grok / client:

[mcp_servers.discourse]
command = "node"
args = ["/ABS/PATH/discourse-mcp/dist/index.js", "--profile", "/path/to/profile.json"]
enabled = true
startup_timeout_sec = 60

libcurl-impersonate

Resolution order (impers native):

1. LIBCURL_IMPERSONATE_PATH

2. LIBCURL_PATH

3. Common install paths

4. GitHub download into ~/.cache/impers/libcurl-impersonate/{platform}-{arch}/

5. System libcurl (no impersonate)

If step 4 fails (e.g. API rate limit), this fork tries gh:

brew install gh && gh auth login   # recommended once

Override: DISCOURSE_MCP_REQUIRE_IMPERSONATE=0 allows starting without impersonate (CF sites will usually fail).

CLI / profile flags (same as upstream + extras)

Reading images (for vision models)

MCP tools should return images as Image Content blocks (not only a base64 string inside JSON text):

{
  "content": [
    { "type": "text", "text": "{...metadata...}" },
    { "type": "image", "data": "<base64>", "mimeType": "image/jpeg" }
  ]
}

Use discourse_read_image:

{ "post_id": 8564338, "max_images": 2 }

{ "url": "upload://q9cFN6AzFPTkcn4CVcNmkuXNDTi.jpeg" }

{ "url": "https://asset-cdn.example.com/.../photo.jpeg" }

Typical flow: discourse_read_post → see ![alt](upload://...) in raw → discourse_read_image with post_id or that upload:// URL.

See upstream docs for the rest of the tool list (search, read topic/post, create post/topic, drafts, …).

Upstream

Based on discourse/discourse-mcp (MIT).
Cloudflare / impers / gh bootstrap changes live in this fork only.