How to Integrate with Discourse Forums Using MCP: A Complete Guide

You can integrate with Discourse forums using the official Discourse MCP server (discourse-mcp), which wraps the native Discourse REST API as Model Context Protocol tools that any MCP-compatible client can discover and invoke over HTTP.

The awesome-mcp-servers repository curated by punkpeye lists the official Discourse implementation at line 767, providing a standardized bridge between MCP clients and Discourse instances. This integration allows AI agents, chatbots, and automation scripts to read topics, create posts, and manage forum content without writing custom API wrappers.

Architecture Overview

The Discourse MCP integration follows a three-layer architecture that abstracts the forum's native endpoints behind a standardized protocol.

Component	Function	Protocol Layer
Discourse MCP Server	Exposes Discourse functionality (topics, posts, users, categories) as MCP tools such as list_topics, create_post, and search_users.	Acts as an HTTP service translating MCP JSON-RPC calls to Discourse REST API requests.
MCP Client	Discovers available tools via the list method and invokes them using the call method.	Sends POST requests to the server's /mcp endpoint with structured JSON payloads.
Discourse Forum	Stores and serves the actual forum data.	Receives authenticated API requests from the MCP server and returns JSON responses.

The workflow operates as follows:

1. Discovery: The client POSTs { "method": "list" } to http://localhost:3000/mcp. The server returns a catalog of available tools with their parameter schemas.
2. Invocation: The client POSTs { "method": "call", "tool": "list_topics", "arguments": {...} } to execute a specific operation.
3. Execution: The MCP server authenticates with the Discourse instance using an API key, forwards the request to the appropriate Discourse endpoint (e.g., /t/{id}.json), and returns the normalized result.

Source: The Discourse MCP server entry is documented at line 767 in README.md of the punkpeye/awesome-mcp-servers repository【/cache/repos/github.com/punkpeye/awesome-mcp-servers/main/README.md#L767】.

Installing the Discourse MCP Server

You can run the server via npm or Docker. Both methods require a Discourse URL and API credentials.

npm Installation

npx -y discourse-mcp \
  --discourse-url=https://meta.discourse.org \
  --api-key=YOUR_DISCOURSE_API_KEY \
  --api-username=system

The server starts on http://localhost:3000/mcp by default.

Docker Installation

docker run -p 3000:3000 \
  discourse/discourse-mcp \
  --discourse-url=https://your-forum.com \
  --api-key=YOUR_DISCOURSE_API_KEY \
  --api-username=system

Required parameters:

• --discourse-url: The base URL of your Discourse instance
• --api-key: A global or user-specific API key from Discourse admin settings
• --api-username: The username associated with the API key (typically system for global keys)

Discovering and Calling Discourse Tools

Once the server is running, any MCP client can interact with your forum using standard HTTP POST requests.

List Available Tools

First, discover what operations are available:

const fetch = require('node-fetch');

async function listTools() {
  const response = await fetch('http://localhost:3000/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'list' })
  });
  
  const data = await response.json();
  console.log('Available tools:', data.tools);
}

listTools();

The response includes tool definitions such as:

{
  "name": "list_topics",
  "description": "List topics in a given category",
  "parameters": {
    "category_id": "integer",
    "page": "integer"
  }
}

Query Topics and Posts

To retrieve topics from a specific category (e.g., category ID 1 for Announcements):

async function getAnnouncements() {
  const response = await fetch('http://localhost:3000/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      method: 'call',
      tool: 'list_topics',
      arguments: {
        category_id: 1,
        page: 1
      }
    })
  });
  
  const data = await response.json();
  return data.result;
}

To fetch a specific post by ID, use the get_post tool:

async function getPost(postId) {
  const response = await fetch('http://localhost:3000/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      method: 'call',
      tool: 'get_post',
      arguments: { post_id: postId }
    })
  });
  
  const data = await response.json();
  return data.result;
}

Create Content Programmatically

Creating posts through MCP maintains the same pattern. The create_post tool requires a topic ID and raw markdown content:

async function createReply(topicId, content) {
  const response = await fetch('http://localhost:3000/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      method: 'call',
      tool: 'create_post',
      arguments: {
        topic_id: topicId,
        raw: content
      }
    })
  });
  
  const data = await response.json();
  console.log('Created post ID:', data.result.post_id);
  return data.result;
}

// Usage
createReply(123, "This is an automated response via MCP integration.");

Configuration and Authentication Security

The MCP server stores no persistent credentials; it authenticates each request to the Discourse API using the key provided at startup.

Best practices:

• Create a dedicated API user in Discourse with minimal required permissions (e.g., only create_post and read scopes if the client only needs to read and reply).
• Run the MCP server behind a firewall or reverse proxy if exposed to the internet, as it handles authentication headers.
• Use environment variables instead of command-line flags for the API key in production deployments:

export DISCOURSE_API_KEY="your-key-here"
npx -y discourse-mcp --discourse-url=https://forum.example.com

Summary

• The Discourse MCP server (discourse/discourse-mcp) bridges Discourse forums and MCP clients via HTTP, as cataloged in punkpeye/awesome-mcp-servers at line 767.
• Installation requires only npx or Docker, plus a Discourse API key and URL.
• Discovery uses the list method to expose tools like list_topics, get_post, and create_post with full JSON schemas.
• Invocation sends POST requests to /mcp with method: "call" and tool-specific arguments.
• Authentication passes through to the underlying Discourse instance, maintaining native security boundaries.

Frequently Asked Questions

What MCP tools are available for Discourse integration?

The Discourse MCP server exposes tools including list_topics, get_post, create_post, search_users, and category management functions. Each tool accepts parameters matching the Discourse REST API (e.g., category_id, post_id, raw for content) and returns standardized JSON via the MCP protocol.

Do I need to modify my Discourse instance to use MCP?

No modifications are required. The MCP server communicates through Discourse's standard REST API, which is enabled by default on all Discourse installations. You only need to generate an API key from the Admin > API section of your Discourse dashboard.

Can I use this integration with Claude Desktop or other AI assistants?

Yes. Any MCP-compatible client—including Claude Desktop, Glama, or custom Python/Node.js agents—can connect to the Discourse MCP server. Configure the client to point to http://localhost:3000/mcp (or your deployed URL), and the assistant will automatically discover available forum operations through the protocol's tool listing mechanism.

How do I handle rate limiting when using the Discourse MCP server?

The MCP server forwards rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) from the Discourse API. Your MCP client should implement retry logic when receiving 429 status codes. For high-volume automation, consider increasing rate limits in your Discourse admin settings or using a dedicated API user with elevated limits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}