Skip to main content
Glama
Sign In
discourse-mcp

discourse-mcp

by discobrain
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

discourse-mcp

A small MCP stdio server that gives an AI agent tools to read and act on a single Discourse forum — a focused, dependency-free Python fork of the official @discourse/mcp.

  • Python stdlib only. No Node, no npm, no third-party packages. Talks to Discourse over urllib, speaks MCP (JSON-RPC 2.0, newline-delimited) over stdio.

  • Single-site, one identity. Credentials come from the environment; there are no profiles, no multi-site auth_pairs, and no discourse_select_site bootstrap. A bot serves one forum as one user.

  • The forum tools a participant needs — plus the ones @discourse/mcp lacks: reading, posting, and private messages, and liking, custom-emoji reactions, bookmarking, watch/track/mute, and reading the bot's own notifications.

Built as the agent's "hands" for discourse-acp (an ACP harness), but it is a plain MCP server — any MCP client can spawn it.

Install

pip install .            # or: pipx install .

Installs a discourse-mcp console script.

Related MCP server: MCP for Flarum

Configure (environment)

Env var

Required

Meaning

DISCOURSE_URL

yes

forum base URL, e.g. https://forum.example.com

DISCOURSE_API_KEY

yes

API key for the bot account

DISCOURSE_API_USERNAME

yes

the bot's username (Api-Username)

DISCOURSE_MCP_ALLOW_WRITES

no (default 0)

1 to enable write tools (post/like/bookmark/…)

DISCOURSE_MCP_MAX_READ_LENGTH

no (default 50000)

truncate raw post bodies to this many chars

DISCOURSE_MCP_DEFAULT_SEARCH

no

prefix prepended to every search query

A global admin key acts as api_username; a per-user key acts as that user. Either way the bot posts as itself — there is no acting-user impersonation.

Run

discourse-mcp            # run the MCP server on stdio (what an MCP client spawns)
discourse-mcp selftest   # drive initialize + tools/list + tools/call, no network
discourse-mcp tools      # print the full tool catalog as JSON

An MCP client (e.g. Claude Code, or claude-agent-acp) spawns it as a stdio server. Example client config:

{ "command": "discourse-mcp",
  "env": { "DISCOURSE_URL": "https://forum.example.com",
           "DISCOURSE_API_KEY": "…", "DISCOURSE_API_USERNAME": "mybot",
           "DISCOURSE_MCP_ALLOW_WRITES": "1" } }

Tools

All names are prefixed discourse_. Read tools are always available; write tools appear only when DISCOURSE_MCP_ALLOW_WRITES=1. Read tools return a compact projection (not raw Discourse JSON) and truncate bodies to DISCOURSE_MCP_MAX_READ_LENGTH.

Reads: search, read_topic, read_post, get_user, list_categories, list_notifications (the bot's own feed — a side-effect-free peek), read_private_message, list_private_messages.

Writes: create_post, create_topic, update_post, create_private_message, reply_private_message, like_post, unlike_post, react_post (custom emoji; needs the discourse-reactions plugin), bookmark, delete_bookmark, watch_topic (muted / regular / tracking / watching).

Relation to @discourse/mcp

This is intentionally not a 1:1 port. The official server exposes ~100 tools across many admin/opt-in toolsets (workflows, themes, webhooks, data-explorer, AI, …). This fork keeps the surface a conversational forum participant actually uses and adds the day-to-day engagement actions the official server omits (likes/reactions/bookmarks/watch, own-notifications). Tool names and the projected read shapes mirror @discourse/mcp where they overlap.

MCP compliance

Protocol version 2025-06-18 (falls back gracefully to the client's requested version). Implements initialize, notifications/initialized, tools/list, tools/call, and ping. NDJSON stdio framing; stdout carries only protocol messages, all logging goes to stderr.

Available Tools

8 tools
discourse_get_userGet UserB
Read-only

A user's public profile: name, trust level, bio (About Me), staff flags.

Inputs: username (required).

discourse_list_categoriesList CategoriesA
Read-only

List the forum's categories (id, name, slug, topic count).

Inputs: no named parameters.

discourse_list_notificationsList My NotificationsA
Read-only

The bot's OWN notifications (mentions, replies, likes, PMs). Read-only peek; does not clear unread.

Inputs: limit, filter.

discourse_list_private_messagesList Private MessagesA
Read-only

List the bot's private-message topics in a mailbox.

Inputs: page, mailbox, per_page.

discourse_read_postRead PostA
Read-only

Read a single post's raw markdown and metadata by post id.

Inputs: post_id (required).

discourse_read_private_messageRead Private MessageA
Read-only

Read a private-message topic's posts (raw). Errors if the topic is not a PM.

Inputs: topic_id (required), post_limit, start_post_number.

discourse_read_topicRead TopicA
Read-only

Read a topic's posts (raw markdown), oldest first from an optional start.

Inputs: topic_id (required), post_limit, start_post_number.

discourse_searchSearchA
Read-only

Full-text search of the forum; returns matching topics (id, slug, title).

Inputs: query (required), page, max_results.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool maps to a distinct resource/action: search, topic, post, user, categories, notifications, PM list, and PM content. The two PM tools are clearly list-vs-read, and read_private_message's error behavior clarifies its boundary.

    Naming Consistency4/5

    Tool names consistently use snake_case and the discourse_ prefix, but the verb choice is slightly mixed across search, read, get, and list. This is mostly predictable, with minor deviations like discourse_get_user standing apart from the discourse_read_* content tools.

    Tool Count5/5

    Eight tools is a well-scoped size for a read-only Discourse client. Each tool earns its place, covering public reading, search, user info, categories, notifications, and private messages without redundancy.

    Completeness3/5

    The read-only surface covers the main resources, but there is no direct way to list or browse topics, such as latest topics or topics within a category, so discovery depends heavily on search. Write/reply operations are also absent, which is consistent with a read-only intent but limits full forum workflows.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • MCP for Flarum

      linkrobins
      A
      license
      A
      quality
      F
      maintenance
      Provides MCP-compatible AI clients with full access to a Flarum forum's API, enabling reading, searching, creating discussions, replying, moderation, and management of users, tags, and groups.
      15
      1
      MIT

    • delphi-mcp

      CaryWang1234
      A
      license
      Not graded
      quality
      C
      maintenance
      A read-only MCP server that lets an AI agent browse and read the Chief Delphi robotics forum — scoping categories, finding and reading threads, and vetting user profiles — using only anonymous public endpoints, with no account, API key, or write access. It enforces the site's robots.txt rules and throttles requests, and can be pointed at any Discourse forum via a base-URL setting.
      32 npm
      MIT