Discourse MCP Setup in OpenCode CLI

Wiki Users
, ,
1

This guide provides tested instructions for installing the Discourse MCP into OpenCode CLI. If you’re using a different MCP client, I have also written guides for Codex CLI.

USE YOUR LLM! LLMs are very good at following instructions and can do the setup for you. Point the LLM at this guide by URL and ask it to do the setup. You can also ask it to explain any steps you don’t understand.

Prerequisites

  • Node.js installed (24 LTS recommended)
  • OpenCode CLI installed
  • Access to the intended Discourse forum as an ordinary user (no need to be an admin!)

It’s important to realise that there are three separate components here:

  1. The remote Discourse forum, which is the source of data and the target for actions.

  1. The Discourse MCP server, which is an open-source locally-running tool that connects to Discourse and provides an API for OpenCode to interact with Discourse. This is installed as an NPX package and launched on demand by OpenCode CLI.

  1. OpenCode CLI, which is the MCP client that connects to the MCP server and provides the interface for interacting with Discourse through the MCP API.

1. Generate the User API key

This will authenticate you to Discourse and this is how you will get your API key. npx will download and run the code, nothing needs to be installed in the traditional sense.

In a terminal, run:

npx @discourse/mcp@latest generate-user-api-key \
  --site =DISCOURSE-FORUM= \
  --save-to =PROFILE-PATH=/=NAME=.json

Example:

npx @discourse/mcp@latest generate-user-api-key \
  --site https://meta.discourse.org \
  --save-to ~/.config/opencode/discourse-profiles/meta.json

Approve the browser consent and copy back the encrypted data, which proves your ability to login and generates an API key which is saved to =PROFILE-PATH= for use by the MCP server.

The API key will have the same level of access to the forum that you have as a user.

2. Add the MCP server to OpenCode CLI

Edit your OpenCode configuration file at ~/.config/opencode/opencode.jsonc and add the following entry to the mcp section:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // ... other MCP servers ...
    "discourse-=NAME=-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@discourse/mcp@latest",
        "--profile",
        "=PROFILE-PATH=/=NAME=.json",
      ],
      "enabled": true,
      "environment": {},
    },
  },
}

Example:

"discourse-meta-mcp": {
  "type": "local",
  "command": [
    "npx",
    "-y",
    "@discourse/mcp@latest",
    "--profile",
    "/home/marcus/.config/opencode/discourse-profiles/meta.json"
  ],
  "enabled": true,
  "environment": {},
},

The MCP server will be launched on demand with npx by OpenCode CLI when you start OpenCode. It is configured to use the profile at =PROFILE-PATH= and by default it is read-only.

3. Restart OpenCode CLI

Fully restart OpenCode so it reloads the configuration and connects to the MCP server.

If it starts without errors, the Discourse MCP server is working. You can ask OpenCode to refer to your Discourse forum for information - especially information you have access to but is not public - this will verify it is connecting as you.

4. Enable Write Features (Optional)

By default, the Discourse MCP server runs in read-only mode. To enable write operations (creating posts, topics, users, etc.), you need to add two flags to your profile JSON file.

Edit =PROFILE-PATH=/=NAME=.json and add "read_only": false and "allow_writes": true as siblings to the auth_pairs array:

{
  "read_only": false,
  "allow_writes": true,
  "auth_pairs": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Example:

{
  "read_only": false,
  "allow_writes": true,
  "auth_pairs": [
    {
      "site": "https://meta.discourse.org",
      "user_api_key": "abc123def456ghi789jkl012mno345pqr",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

After adding these flags, restart OpenCode CLI for the changes to take effect. The MCP server will now allow write operations like:

  • Creating and updating topics
  • Creating posts and replies
  • Managing drafts
  • Uploading files
  • Creating categories (if you have permission)
  • Managing users (if you have admin permission)

Warning: Write operations will use your user account’s permissions. Any content created will appear as if you created it manually. Use write features responsibly.

Managing Multiple Discourse Instances

You can add multiple Discourse forums by repeating the process with different profile files and MCP server names:

"discourse-meta-mcp": {
  "type": "local",
  "command": [
    "npx", "-y", "@discourse/mcp@latest",
    "--profile", "/home/username/.config/opencode/discourse-profiles/meta.json"
  ],
  "enabled": true,
  "environment": {},
},
"discourse-mycommunity-mcp": {
  "type": "local",
  "command": [
    "npx", "-y", "@discourse/mcp@latest",
    "--profile", "/home/username/.config/opencode/discourse-profiles/mycommunity.json"
  ],
  "enabled": true,
  "environment": {},
},

Configuration Files

There are two main files:

  1. =OPENCODE-CONFIG= - OpenCode CLI configuration file at ~/.config/opencode/opencode.jsonc, which includes the MCP server settings.

  2. =PROFILE-PATH= - The profile for the Discourse MCP server, which includes the API key and other settings for connecting to Discourse.

OpenCode Settings

The settings for connecting to the MCP server are in =OPENCODE-CONFIG= (typically ~/.config/opencode/opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "discourse-=NAME=-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@discourse/mcp@latest",
        "--profile",
        "=PROFILE-PATH=/=NAME=.json",
      ],
      "enabled": true,
      "environment": {},
    },
  },
}

OpenCode MCP Settings documentation: OpenCode Documentation

Discourse MCP Settings

The settings for the Discourse MCP server itself are in =PROFILE-PATH=/=NAME=.json=:

{
  "auth_pairs": [
    {
      "site": "=DISCOURSE-FORUM=",
      "user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "user_api_client_id": "discourse-mcp"
    }
  ]
}

Discourse MCP settings documentation: GitHub - discourse/discourse-mcp

Security Best Practices

It’s recommended to:

  1. Store profile files in a dedicated directory (e.g., ~/.config/opencode/discourse-profiles/)
  2. Add this directory to .gitignore if you’re tracking your dotfiles in version control
  3. Use descriptive names for your profile files (e.g., meta.json, mycommunity.json)
  4. Keep API keys private - they have the same access level as your user account

Troubleshooting

  • Connection issues: Verify the profile path in opencode.jsonc is correct and the file exists
  • Authorization errors: Check that the API key hasn’t been revoked in your Discourse user preferences
  • Permission errors: Ensure you have the required permissions on the Discourse instance
  • Restart required: Changes to opencode.jsonc require restarting OpenCode CLI
2 Likes