discourse/mcp

List concise database-backed custom-tool summaries and compact live preset metadata. Scripts, bindings, verbose parameter descriptions, and full records are omitted; use discourse_ai_get_custom_tool or the guide's preset lookup to zoom in. Requires admin credentials.

List visible computed Discourse AI modules, feature enabled state, assigned agents, and effective LLMs. Requires admin credentials.

List staff-visible posts classified positive, negative, or neutral by Discourse AI for an exact category/tag and date window. Classification is model output, not proof of tone, satisfaction, risk, or an argument.

Run Guardian-filtered Discourse AI semantic search and return bounded grouped post/topic evidence. Requires Discourse AI embeddings. Results are bounded and expose no fabricated page cursor.

Actually execute a persisted or unsaved custom-tool script. It can make external requests and cause side effects; this is not dry validation. Requires admin credentials and write mode.

Partially update one AI agent, including enabled state, permissions, model, prompt, tools, subagent delegation, and RAG configuration. Only supplied fields are sent. Requires admin credentials and write mode.

Partially update a scripted tool. Call the guide before substantial script changes. Omitted scalar fields and RAG uploads are preserved; changing secret_contracts can prune orphan bindings unless secret_bindings are supplied. Raw secret values are never accepted. Requires admin credentials and write mode.

Atomically bulk-update only non-secret settings freshly exposed by one exact AI feature area, with optional compare-before-write original_values. Refreshes effective state afterward. Production behavior changes immediately. Requires admin credentials and write mode.

Create a new category. Returns JSON with id, slug, and name.

Create a custom group with complete core settings, initial members and owners, custom fields, associations, and optional plugin fields. Requires staff group-creation permission.

Create a post in a topic. author_username requires a global API key. Returns the actual upstream author so callers can verify attribution.

Create a private message for typed user, group, or email recipients. Unknown emails may create staged users. author_username requires a global API key; the response reports actual attribution.

Create a new saved Data Explorer query. Requires admin API key and write access.

Create a tag group with an explicit complete permission list such as permissions: [{group_id: 0, access: "full"}] for everyone, nonempty members, an optional parent selector, and one-per-topic policy. Omit parent_tag or use null when there is no parent; blank placeholders are safely treated as omitted. New tag names require allow_tag_creation=true because they create persistent tags and trigger normal indexing/plugin hooks. Duplicate-name and ID checks are advisory; upstream staff authority, tagging_enabled, and constraints remain authoritative.

Create a local Discourse theme or component. For textual HTML/SCSS/JS fields provide value and omit upload_id; for assets provide numeric upload_id with type=upload and omit value. Supplied code can execute or deploy for visitors; explicit confirmations and admin write access are required.

Create a new topic. author_username requires a global API key. Returns the actual upstream author so callers can verify attribution.

Create a user through Discourse's signup API using a global admin API key. Reports whether upstream confirmed creation; anti-enumeration responses without user_id remain indeterminate. Optional avatar assignment runs only after confirmed creation.

Create a guarded outbound webhook using the live event and content-type catalog. External delivery and risky options require explicit confirmation.

Create a draft from a complete small graph or template. Prefer a complete graph over blank creation. Authoring loop: inspect the slim node catalog, request identifiers for schemas and output keys, resolve entity ids, create from a template or complete graph, GET before edits, test the draft, then publish. Interpolating strings start with =. Filter/if use leftValue/rightValue and output ports true/false. Connection type is the source output key, not always main. Prefer declarative nodes over action:code. Manual runs execute the current draft. Omitting a node on whole-graph update deletes it. no…

Delete a draft by key. Requires current sequence number to prevent conflicts.

Permanently delete a custom group. Automatic groups cannot be deleted. Requires staff access.

Soft-delete a Data Explorer query. The query can be restored by an admin. Requires admin API key and write access.

Permanently delete one exact tag group after fresh name/state-hash checks and explicit acknowledgements for category relationship cascades and unresolved plugin dependencies. Deletion removes memberships, permissions, and category allowed/required relationships, but not tags or topic-tag rows. Dependency discovery is not exhaustive (plugins such as RSS polling may depend on groups). Scoped API keys may not include this delete route. A 200 response is only dispatch acknowledgement; absence is verified before success.

Permanently delete one non-system, non-default theme/component after a fresh exact-name check. Dependencies are not detached automatically and bulk deletion is not exposed.

Delete one webhook after a fresh exact destination-fingerprint precondition.

Permanently delete a workflow. Fails when another workflow calls it.

Replace the draft with its published snapshot. Requires an existing published version.

Evaluate a workflow expression without mutating the forum. Interpolating expressions start with =.

Discover topics through a filtered, top, or hot view. Filtered uses Discourse TopicsFilter syntax; top uses Discourse's authoritative top score and defaults to weekly; hot is defined exactly as daily top (not sentiment, controversy, or real-time velocity). Returns a uniform rich topic projection and truthful pagination metadata.

Get messages from a chat channel. Returns JSON object with channel_id, messages array (id, username, created_at, message, edited, thread_id, in_reply_to_id), and meta.

Retrieve a specific draft by key. Returns JSON with draft_key, sequence, and parsed data (title, reply, categoryId, tags, action).

Get complete visible group details by numeric ID or name, including caller capabilities and group settings.

Read reply relationships for a post as recursive descendant IDs, bounded rich direct replies, or the upstream-bounded ancestor history. Preserves upstream ordering and references.

Get a staff/Guardian-authorized post revision with bounded diffs, edit reason, actor, version, and hidden-state evidence.

Get full details of a Data Explorer query including SQL and parameters. Requires admin API key.

Execute one discovered staff-visible Discourse report with dates, facets, typed filters, limit, and upstream caching. This exposes existing reports, not arbitrary SQL.

Get the authoritative count of pending reviewable records visible to the authenticated user. This counts queue items, not individual flag/score records; upstream Guardian permissions remain authoritative.

Refresh one shortlisted reviewable's bounded context, current version, claim state, scores, and exact dynamic actions. Paginated list results already include evidence/actions, so do not fan this tool out across the queue. Optionally includes Discourse's score explanation; never generates a recommendation.

Get the staff Solved support dashboard. Requires Discourse Solved. 'Unanswered' means unsolved with no qualifying regular reply, not no reply from a configured support team.

Get authoritative tag-group state by ID. Requires a locally configured API credential and upstream staff authority. The deterministic state_hash is an MCP optimistic precondition, not an upstream atomic lock; a race remains possible after preflight.

Inspect one local, ZIP-imported, or Git-backed Discourse theme/component as an administrator. Source values are bounded, opt-in, and may be unavailable for remote records; private key material is never returned.

Get up to 300 ascending daily topic view counts. Views combine anonymous and logged-in views; they are not unique viewers or an engagement judgment.

Get user info. Returns JSON with id, username, name, trust_level, created_at, bio, admin, and moderator.

Get staff-authorized behavioral moderation counters for a user. Omits unrelated administrative capability flags; Discourse permissions remain authoritative.

Get profile-visible aggregate user activity, top topics/replies/links, interaction partners, categories, badges, likes, visits, reading, and post/topic counts. Missing metrics remain null when hidden or unavailable.

Get one fresh safe webhook configuration for inspection and mutation preconditions.

Get the complete round-trippable workflow graph. GET immediately before updating it.

Poll an execution for status, errors, timing, trigger data, and steps.

Approve or deny one pending group membership request. Approval adds the requester to the group; denial only removes the request.

Install a Git repository or ZIP/gzip archive. Set source to exactly one nested variant: {kind:repository, remote_url...}, {kind:archive, archive_data...}, or {kind:archive, archive_path...}; never add placeholder fields from another variant. External code and migrations can have site-wide impact and are not sandboxed.

Add existing accounts immediately when an address matches, and invite unknown addresses to the forum with this group preassigned. Use add_group_members_by_email when every address is known to belong to an account.

Add a user or group to a private message, or submit an opaque email invitation. Email success does not confirm delivery or participant access. author_username requires a global API key.

Join a visible group that allows public admission as the authenticated user.

Leave a group that allows public exit as the authenticated user.

Exhaustively list categories visible to the selected identity through bounded pagination. Returns stable IDs, slugs, hierarchy (parent_category_id; pid is a legacy alias), access flags, counts, structured completion metadata, and JSON text fallback. Opt in with the administration toolset.

List user-directory/cohort metrics with authoritative totals and continuation. Supports Discourse periods, ordering, visible groups, page 0-10, and the upstream maximum of 50 rows.

List a group's members and owners with filtering, ordering, and pagination. Visibility is enforced by Discourse.

List pending membership requests and reasons for a group the caller can manage, with filtering and pagination.

List visible posts authored by a group using Discourse's fixed 20-row page, ID or timestamp cursor, and optional category filter. Group authorship is cohort evidence, not proof of organizational responsibility.

List visible groups. Empty input exhaustively traverses the bounded directory; any explicit page or filter field preserves the existing single-page query behavior. Both modes return one structured envelope with truthful completion metadata and JSON text fallback. Opt in with the groups toolset.

List the site's latest visible posts using Discourse's fixed 50-post page and post-ID cursor. Anonymous upstream responses expire after one minute; results are a feed, not an exhaustive history.

List authenticated personal or group private-message mailboxes. Returns normalized JSON messages and pagination metadata.

Discover staff-visible Discourse report identifiers and metadata. The catalog is authoritative because core and plugins can add or hide reports.

Non-exhaustive topic-level signal only: list pending topics at or above Discourse's minimum review priority. Do not use this tool to work through or rank the full queue because it omits reviewable IDs, actions, low-priority items, and items without topics. Use discourse_list_reviewables for moderation triage.

Work through the exhaustive visible Discourse queue in pages of 10. For ordinary triage, call with only status=pending and offset=0—do not guess topic/category/type filters. Use meta.total and follow next_offset while has_more is true. Each result already includes bounded evidence and exact dynamic actions; fetch detail only for a shortlisted item that needs fresher context.

List admin-visible Discourse site settings with bounded metadata, optionally returning only settings whose current value differs from the default. Secret and credential-like values are always masked.

Authoritative unpaginated tag-group inventory ordered by name. Requires a locally configured API credential and upstream staff authority; Discourse returns a privacy-preserving 404 to non-staff. Staff reads can work when tagging is disabled. Returns canonical tags, parent, one-per-topic, explicit permissions entries ({group_id, access}; group_id 0 is everyone), and optimistic state hashes.

List admin-visible Discourse themes and components. This opt-in admin read returns bounded summaries and local pagination; it does not expose theme source code.

List a user's visible activity using model-friendly action names. Plugin-backed action families can legitimately be empty; emptiness does not prove that a feature is unavailable.

Get paginated list of user posts/replies. Returns JSON object with posts array (id, topic_id, post_number, slug, title, created_at, excerpt, category_id) and meta (page, limit, has_more).

List users via admin API. Requires admin API key. Returns ~100 users per page (Discourse's fixed page size). Returns JSON with users array and pagination meta.

List bounded webhook delivery diagnostics. Payload and response previews are omitted unless explicitly confirmed.

List safe webhook summaries and the live authoring catalog without exposing webhook secrets or destination credentials.

List workflow credentials with secrets redacted. Credential creation remains in the admin UI.

List global or per-workflow execution history.

List a slim catalog, or pass identifier for schemas, ports, and output contracts. Authoring loop: inspect the slim node catalog, request identifiers for schemas and output keys, resolve entity ids, create from a template or complete graph, GET before edits, test the draft, then publish. Interpolating strings start with =. Filter/if use leftValue/rightValue and output ports true/false. Connection type is the source output key, not always main. Prefer declarative nodes over action:code. Manual runs execute the current draft. Omitting a node on whole-graph update deletes it. nodes and connections…

List templates or retrieve a complete template graph by id. Authoring loop: inspect the slim node catalog, request identifiers for schemas and output keys, resolve entity ids, create from a template or complete graph, GET before edits, test the draft, then publish. Interpolating strings start with =. Filter/if use leftValue/rightValue and output ports true/false. Connection type is the source output key, not always main. Prefer declarative nodes over action:code. Manual runs execute the current draft. Omitting a node on whole-graph update deletes it. nodes and connections must always be sent t…

List workflow version history and UUIDs available for restore.

List compact Discourse Workflow summaries. Requires an admin API key.

Activate, approve, activate-and-approve, or deactivate one user through Discourse's authoritative admin routes. Requires explicit confirmation and upstream staff authorization.

Perform one exact dynamic action after a fresh serialized preflight. Choose by the action's full description, not label alone (for example delete-and-agree differs from delete-and-ignore). The displayed action ID may be UI-prefixed; this tool safely routes its server_action. Requires confirm=true and write enablement.

Enqueue one explicitly confirmed external webhook ping after a fresh destination precondition.

Read a specific post. Returns JSON with id, topic_id, post_number, username, created_at, and raw content.

Read an authenticated private message, its posts, and direct allowed-user and allowed-group records. Rejects public topics.

Read topic metadata and posts. Large post limits can require multiple upstream requests. For moderation queues, prefer reviewable list/detail evidence instead of fanning this tool out across flagged topics.

Read exact, earliest, latest, around-post, or username-filtered topic evidence. Selection is bounded to 50 posts and reports the visible stream size without claiming the entire topic was loaded.

Redeliver exactly one old webhook event after destination, ownership, and status preconditions. Bulk redelivery is not exposed.

Safely reply to an existing private message after verifying its archetype. author_username requires a global API key; the response reports actual attribution.

Request membership in a visible group that allows requests, sending the reason to its owners.

Resolve category, tag, group, user, badge, chat channel, or data-table ids for workflow parameters.

Restore a historical workflow version by UUID into the draft.

Execute a Data Explorer query with parameters. Returns columns, rows, result_count, duration_ms. Queries run in read-only transactions with 10-second timeout. Requires admin API key.

Run the current unpublished draft asynchronously. This can create posts, send chat, or call external HTTP; poll the returned execution id.

Run one non-trigger, non-waiting draft node asynchronously. Requires upstream pin-data or a prior successful run.

Create or update a draft. Returns JSON with draft_key and new sequence number.

Search site content. Returns JSON object with results array of matching topics (id, slug, title) and meta (total, has_more).

Search post-level evidence with Discourse query syntax. Unlike discourse_search, this preserves matched posts, highlighted blurbs, authors, topics, categories, and truthful bounded continuation. This is keyword search, not Discourse AI semantic search.

Public visibility-filtered tag-group search. q and names combine with AND semantics; upstream treats % and _ in q as SQL LIKE wildcards. Results intentionally omit group IDs, parent tags, and permissions and are not authoritative staff inventory. Exact case-insensitive group name is the supported correlation key. Always sends an explicit limit and reports possible truncation.

Validate and select a Discourse site. Returns JSON with site URL and title.

Check or install updates for an existing Git-backed theme. Both actions clone external code and persist state; update deploys code and runs settings migrations, requiring explicit confirmations.

Update all core group profile, visibility, admission, notification-default, association, email, SMTP, custom, and plugin settings supported by the caller and group type.

Update the content of an existing post. Returns JSON with updated post details.

Update an existing Data Explorer query. Only provided fields are updated. Requires admin API key and write access.

Set or reset one ordinary admin-visible Discourse site setting after a fresh optimistic-concurrency check. Secret and structured settings are excluded.

Safely replace complete tag-group state after a fresh expected_state_hash preflight. Omitted mutable fields are preserved locally, but Discourse receives full tags, parent, one-per-topic, and permissions because partial upstream bodies clear state. For parent_tag, omit or pass a blank placeholder to preserve the current parent; pass null to clear it. Permissions use explicit {group_id, access} entries; group_id 0 means everyone. Tag/parent removals, permission replacement, and possible materialization of serializer-synthesized everyone/full permissions require explicit acknowledgements. The ha…

Update bounded metadata, default status, or complete theme-component relationships. Relationship arrays replace the entire graph side; source, settings, translations, and remote refresh are intentionally excluded.

Replace or explicitly delete selected fields on a local or ZIP-imported theme. Text replacements require value and prohibit upload_id; asset replacements require numeric upload_id with type=upload and prohibit value. This can deploy executable code; Git-backed and system themes are rejected.

Set or explicitly revert one declared setting owned by a theme/component. This does not mutate themeable global site settings; object values are validated upstream against the declared schema.

Replace values for explicit translation keys declared by a theme, after a fresh locale read. Unknown keys are rejected; deletion/revert is not supported in this release.

Update an existing topic (title, category, tags, featured_link). Returns JSON with updated topic details.

Update user profile fields. If upload_id is provided, also sets the user's avatar. Returns JSON with success status and updated user details.

Partially update a webhook after fresh destination and active-state preconditions. Relationship arrays are complete replacements.

GET first. A replace PUT replaces the whole draft graph; omitted nodes are deleted. Use complete nodes+connections or operations[], never both. Authoring loop: inspect the slim node catalog, request identifiers for schemas and output keys, resolve entity ids, create from a template or complete graph, GET before edits, test the draft, then publish. Interpolating strings start with =. Filter/if use leftValue/rightValue and output ports true/false. Connection type is the source output key, not always main. Prefer declarative nodes over action:code. Manual runs execute the current draft. Omitting …

Pin test items to a node name, or omit items to unpin it.

Upload an image or file to Discourse. Provide either: image_data (base64 with filename), a remote HTTP(S) URL, or an absolute local file path. user_id is required for avatar/background uploads. Returns upload_id for use in avatar/profile updates. Use short_url to embed images in posts.

Upload a bounded local/base64 asset for later attachment to a theme field. No remote URL fetch is supported; upload alone does not attach or deploy the asset.