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

> Learn how to integrate with Discourse forums using the official Discourse MCP server. This guide explains how to leverage the native Discourse REST API for seamless forum integration. Get started today!

- Repository: [Frank Fiegel/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/punkpeye/awesome-mcp-servers/blob/main/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

```bash
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

```bash
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:

```javascript
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:

```json
{
  "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):

```javascript
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:

```javascript
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:

```javascript
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:

```bash
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.