Overview

This MCP (Model Context Protocol) server provides a lightweight, developer-friendly API to search and export posts from a Discourse forum. It acts as a retrieval layer between your application or LLM toolchain and a Discourse instance, exposing simple endpoints to query posts by full text, category, tag, author, and date ranges. The server is designed to make it easier to surface relevant forum content as model context or to extract data for analytics and moderation workflows.

By centralizing common search operations and optional export features (CSV/JSON), the server saves you from writing repetitive code against the raw Discourse API. It supports pagination, result filtering, and configurable caching to reduce load on your forum. Typical uses include document retrieval for retrieval-augmented generation, moderation audits, triage dashboards, and bulk data exports.

Features

Full-text search across Discourse posts and topics
Filter by category, tag(s), user, date range, and topic status
Pagination and sorting (relevance, newest, oldest)
Export results to JSON and CSV
Authentication via Discourse API key/username
Optional caching for repeated queries
Simple, documented HTTP endpoints for integration with tools and LLMs
Docker-friendly for containerized deployment

Installation / Configuration

Prerequisites:

Node.js 16+ (or check repository for the exact runtime)
A Discourse API key and API username with read permissions
Access to your Discourse instance URL

Clone and install:

git clone https://github.com/AshDevFr/discourse-mcp-server.git
cd discourse-mcp-server
npm install

Create a .env file (example):

# .env
PORT=3000
DISCOURSE_BASE_URL=https://discourse.example.com
DISCOURSE_API_KEY=your_api_key_here
DISCOURSE_API_USERNAME=system
CACHE_TTL_SECONDS=300
DEFAULT_PAGE_SIZE=25

Run locally:

npm start
# or for development with auto-reload
npm run dev

Docker (example Dockerfile provided in repo; build & run):

docker build -t discourse-mcp-server .
docker run -e DISCOURSE_BASE_URL=https://discourse.example.com \
           -e DISCOURSE_API_KEY=your_api_key \
           -e DISCOURSE_API_USERNAME=system \
           -p 3000:3000 \
           discourse-mcp-server

Configuration options (env vars summary):

Variable	Purpose	Default
DISCOURSE_BASE_URL	Base URL of your Discourse instance	required
DISCOURSE_API_KEY	Discourse API key for authorized requests	required
DISCOURSE_API_USERNAME	API username (often `system`)	required
PORT	HTTP port to listen on	3000
CACHE_TTL_SECONDS	In-memory cache TTL for search results	300
DEFAULT_PAGE_SIZE	Number of results per page	25

Available Tools / Resources

The server exposes a small set of HTTP endpoints (examples below). These can be used directly from your application or registered as tools in an LLM orchestration system that supports MCP-style tool calls.

Common endpoints:

GET /search — search posts/topics with filters
GET /posts/:id — fetch a single post by ID
GET /topics/:id — fetch a topic summary and posts
GET /export — run a search and return CSV or JSON export
GET /meta/categories — list forum categories
GET /meta/tags — list popular tags
GET /meta/users — search users (by username or id)

Example: simple curl search

curl "http://localhost:3000/search?q=rate%20limiting&category=platform&tags=api,performance&page=1&limit=50"

Response shape (JSON):

{
  "total": 235,
  "page": 1,
  "limit": 50,
  "results": [
    {
      "post_id": 123,
      "topic_id": 45,
      "username": "alice",
      "category": "platform",
      "tags": ["api","performance"],
      "created_at": "2024-03-01T12:34:56Z",
      "excerpt": "When hitting the rate limit..."
    }
  ]
}

Use Cases

Retrieval-augmented generation (RAG): When answering user queries, call /search to fetch the most relevant forum posts and supply them as context to a language model so answers are grounded in community knowledge.
Moderation & auditing: Filter posts by date range, user, or tag to produce an export (CSV) for external review or regulatory compliance.
Engineering triage: Search for past incidents or feature discussions filtered by tags like “bug”, “performance”, or “regression” to speed debugging and root-cause analysis.
Data export for analytics: Periodically run exports to collect topic/post metadata for analytics pipelines or BI tools.
User support augmentation: Integrate the server into a support bot to surface canonical answers from the community forum in response to support tickets.

Concrete example — export all posts by user “bob” tagged “installation” in January 2025:

curl "http://localhost:3000/search?user=bob&tags=installation&start_date=2025-01-01&end_date=2025-01-31&export=csv" -o bob-installation-jan2025.csv

Notes and Best Practices

Use caching for common queries to reduce load on your Discourse instance.
Respect rate limits on the Discourse server: configure retries and backoff in clients.
For production, run behind an authenticated proxy or VPN; the service uses your Discourse API key and should be protected.
Review the repository README and code for exact environment variable names and additional flags (logging, debug mode, maximum export sizes).

For the latest code, issues, and contribution guidelines, see the GitHub repository: https://github.com/AshDevFr/discourse-mcp-server.

Discourse Forum Post Search MCP Server