Administration (opt-in)

Themes

List Themes

read-onlyidempotentopen-world

discourse_list_themes

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 Themes

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_list_themes",
    "arguments": {
        "kind": "all",
        "query": "string",
        "include_system": true,
        "limit": 100,
        "offset": 0
      }
  }
}

const result = await client.callTool({
  "name": "discourse_list_themes",
  "arguments": {
    "kind": "all",
    "query": "string",
    "include_system": true,
    "limit": 100,
    "offset": 0
  }
});

result = await session.call_tool("discourse_list_themes", arguments={
  "kind": "all",
  "query": "string",
  "include_system": true,
  "limit": 100,
  "offset": 0
})

Parameters

kindstringthemecomponentallall

querystring

include_systembooleantrue

limitinteger[1, 500]100

offsetinteger>= 00

Get Theme

read-onlyidempotentopen-world

discourse_get_theme

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 Theme

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_theme",
    "arguments": {
        "theme_id": 0,
        "include_field_values": false
      }
  }
}

const result = await client.callTool({
  "name": "discourse_get_theme",
  "arguments": {
    "theme_id": 0,
    "include_field_values": false
  }
});

result = await session.call_tool("discourse_get_theme", arguments={
  "theme_id": 0,
  "include_field_values": false
})

Parameters

theme_idintegerrequired

include_field_valuesbooleanfalse

Create Theme

open-world

discourse_create_theme

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 Theme

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_theme",
    "arguments": {
        "name": "string",
        "component": false,
        "user_selectable": true,
        "color_scheme_id": 0,
        "fields": [
          {
            "name": "string",
            "target": "common",
            "operation": "replace",
            "value": "string",
            "type": "html"
          }
        ],
        "set_default": true,
        "confirm_code_execution": true,
        "confirm_set_default": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_create_theme",
  "arguments": {
    "name": "string",
    "component": false,
    "user_selectable": true,
    "color_scheme_id": 0,
    "fields": [
      {
        "name": "string",
        "target": "common",
        "operation": "replace",
        "value": "string",
        "type": "html"
      }
    ],
    "set_default": true,
    "confirm_code_execution": true,
    "confirm_set_default": true
  }
});

result = await session.call_tool("discourse_create_theme", arguments={
  "name": "string",
  "component": false,
  "user_selectable": true,
  "color_scheme_id": 0,
  "fields": [
    {
      "name": "string",
      "target": "common",
      "operation": "replace",
      "value": "string",
      "type": "html"
    }
  ],
  "set_default": true,
  "confirm_code_execution": true,
  "confirm_set_default": true
})

Parameters

namestringrequired

componentbooleanfalse

user_selectableboolean

color_scheme_idinteger

fieldsArray<object>

Optional populated fields. Each item is either a text replacement with value, or an upload replacement with numeric upload_id and type=upload.

set_defaultboolean

confirm_code_executionboolean

confirm_set_defaultboolean

Install Theme

destructiveopen-world

discourse_install_theme

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.

Install Theme

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_install_theme",
    "arguments": {
        "source": {
          "kind": "repository",
          "remote_url": "string",
          "branch": "string",
          "force_placeholder": false
        },
        "confirm_external_code": true,
        "confirm_force_placeholder": true,
        "confirm_replace": true,
        "confirm_run_migrations": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_install_theme",
  "arguments": {
    "source": {
      "kind": "repository",
      "remote_url": "string",
      "branch": "string",
      "force_placeholder": false
    },
    "confirm_external_code": true,
    "confirm_force_placeholder": true,
    "confirm_replace": true,
    "confirm_run_migrations": true
  }
});

result = await session.call_tool("discourse_install_theme", arguments={
  "source": {
    "kind": "repository",
    "remote_url": "string",
    "branch": "string",
    "force_placeholder": false
  },
  "confirm_external_code": true,
  "confirm_force_placeholder": true,
  "confirm_replace": true,
  "confirm_run_migrations": true
})

Request Body

{
  "source": {
    "kind": "repository",
    "remote_url": "string",
    "branch": "string",
    "force_placeholder": false
  },
  "confirm_external_code": true,
  "confirm_force_placeholder": true,
  "confirm_replace": true,
  "confirm_run_migrations": true
}

Body

application/json

sourceobjectrequired

Choose exactly one repository, base64 archive, or local archive source variant. Never add placeholder fields from another variant.

Show child attributes

Any of

Repository installation source

kindstringrequired

remote_urlstringrequired

Git repository URL; archive inputs are not part of this variant

branchstring

force_placeholderbooleanfalse

Base64 archive installation source

kindstringrequired

archive_dataobjectrequired

Bounded base64 archive and filename

Show child attributes

base64stringrequired

filenamestringrequired

replace_theme_idinteger

component_update_modestringnoneadd_missingsyncadd_missing

run_migrationsbooleantrue

Allowlisted local archive installation source

kindstringrequired

archive_pathstringrequired

Absolute local path or file:// URL beneath allowed_upload_paths

replace_theme_idinteger

component_update_modestringnoneadd_missingsyncadd_missing

run_migrationsbooleantrue

confirm_external_codebooleanrequired

confirm_force_placeholderboolean

confirm_replaceboolean

confirm_run_migrationsboolean

Update Theme Metadata

destructiveidempotentopen-world

discourse_update_theme

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.

Update Theme Metadata

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_theme",
    "arguments": {
        "theme_id": 0,
        "name": "string",
        "color_scheme_id": 0,
        "dark_color_scheme_id": 0,
        "user_selectable": true,
        "auto_update": true,
        "enabled": true,
        "parent_theme_ids": [
          0
        ],
        "child_theme_ids": [
          0
        ],
        "set_default": true,
        "expected_name": "string",
        "confirm_default_change": true,
        "confirm_component_graph_replace": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_update_theme",
  "arguments": {
    "theme_id": 0,
    "name": "string",
    "color_scheme_id": 0,
    "dark_color_scheme_id": 0,
    "user_selectable": true,
    "auto_update": true,
    "enabled": true,
    "parent_theme_ids": [
      0
    ],
    "child_theme_ids": [
      0
    ],
    "set_default": true,
    "expected_name": "string",
    "confirm_default_change": true,
    "confirm_component_graph_replace": true
  }
});

result = await session.call_tool("discourse_update_theme", arguments={
  "theme_id": 0,
  "name": "string",
  "color_scheme_id": 0,
  "dark_color_scheme_id": 0,
  "user_selectable": true,
  "auto_update": true,
  "enabled": true,
  "parent_theme_ids": [
    0
  ],
  "child_theme_ids": [
    0
  ],
  "set_default": true,
  "expected_name": "string",
  "confirm_default_change": true,
  "confirm_component_graph_replace": true
})

Request Body

{
  "theme_id": 0,
  "name": "string",
  "color_scheme_id": 0,
  "dark_color_scheme_id": 0,
  "user_selectable": true,
  "auto_update": true,
  "enabled": true,
  "parent_theme_ids": [
    0
  ],
  "child_theme_ids": [
    0
  ],
  "set_default": true,
  "expected_name": "string",
  "confirm_default_change": true,
  "confirm_component_graph_replace": true
}

Body

application/json

theme_idintegerrequired

namestring

color_scheme_idinteger | null

Show child attributes

Any of

integer

null

dark_color_scheme_idinteger | null

Show child attributes

Any of

integer

null

user_selectableboolean

auto_updateboolean

enabledboolean

parent_theme_idsArray<integer>

child_theme_idsArray<integer>

set_defaultboolean

expected_namestring

confirm_default_changeboolean

confirm_component_graph_replaceboolean

Update Theme Fields

destructiveidempotentopen-world

discourse_update_theme_fields

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.

Update Theme Fields

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_theme_fields",
    "arguments": {
        "theme_id": 0,
        "fields": [
          {
            "name": "string",
            "target": "common",
            "operation": "replace",
            "value": "string",
            "type": "html"
          }
        ],
        "expected_theme_name": "string",
        "confirm_code_execution": true,
        "confirm_field_replacement": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_update_theme_fields",
  "arguments": {
    "theme_id": 0,
    "fields": [
      {
        "name": "string",
        "target": "common",
        "operation": "replace",
        "value": "string",
        "type": "html"
      }
    ],
    "expected_theme_name": "string",
    "confirm_code_execution": true,
    "confirm_field_replacement": true
  }
});

result = await session.call_tool("discourse_update_theme_fields", arguments={
  "theme_id": 0,
  "fields": [
    {
      "name": "string",
      "target": "common",
      "operation": "replace",
      "value": "string",
      "type": "html"
    }
  ],
  "expected_theme_name": "string",
  "confirm_code_execution": true,
  "confirm_field_replacement": true
})

Parameters

theme_idintegerrequired

fieldsArray<object>required

expected_theme_namestringrequired

confirm_code_executionbooleanrequired

confirm_field_replacementbooleanrequired

Update Theme Setting

destructiveidempotentopen-world

discourse_update_theme_setting

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.

Update Theme Setting

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_theme_setting",
    "arguments": {
        "theme_id": 0,
        "name": "string",
        "operation": "set",
        "confirm_revert": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_update_theme_setting",
  "arguments": {
    "theme_id": 0,
    "name": "string",
    "operation": "set",
    "confirm_revert": true
  }
});

result = await session.call_tool("discourse_update_theme_setting", arguments={
  "theme_id": 0,
  "name": "string",
  "operation": "set",
  "confirm_revert": true
})

Parameters

theme_idintegerrequired

namestringrequired

valueany

operationstringsetrevertset

expected_current_valueany

confirm_revertboolean

Update Theme Translations

destructiveidempotentopen-world

discourse_update_theme_translations

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 Theme Translations

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_theme_translations",
    "arguments": {
        "theme_id": 0,
        "locale": "string",
        "translations": {},
        "expected_theme_name": "string",
        "confirm_translation_replacement": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_update_theme_translations",
  "arguments": {
    "theme_id": 0,
    "locale": "string",
    "translations": {},
    "expected_theme_name": "string",
    "confirm_translation_replacement": true
  }
});

result = await session.call_tool("discourse_update_theme_translations", arguments={
  "theme_id": 0,
  "locale": "string",
  "translations": {},
  "expected_theme_name": "string",
  "confirm_translation_replacement": true
})

Parameters

theme_idintegerrequired

localestringrequired

translationsobjectrequired

expected_theme_namestringrequired

confirm_translation_replacementbooleanrequired

Sync Remote Theme

destructiveopen-world

discourse_sync_remote_theme

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.

Sync Remote Theme

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_sync_remote_theme",
    "arguments": {
        "theme_id": 0,
        "action": "check",
        "expected_remote_url": "string",
        "confirm_external_code": true,
        "confirm_run_migrations": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_sync_remote_theme",
  "arguments": {
    "theme_id": 0,
    "action": "check",
    "expected_remote_url": "string",
    "confirm_external_code": true,
    "confirm_run_migrations": true
  }
});

result = await session.call_tool("discourse_sync_remote_theme", arguments={
  "theme_id": 0,
  "action": "check",
  "expected_remote_url": "string",
  "confirm_external_code": true,
  "confirm_run_migrations": true
})

Parameters

theme_idintegerrequired

actionstringcheckupdaterequired

expected_remote_urlstring

confirm_external_codeboolean

confirm_run_migrationsboolean

Upload Theme Asset

open-world

discourse_upload_theme_asset

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.

Upload Theme Asset

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_upload_theme_asset",
    "arguments": {
        "file_data": "string",
        "file_path": "string",
        "filename": "string",
        "confirm_asset_upload": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_upload_theme_asset",
  "arguments": {
    "file_data": "string",
    "file_path": "string",
    "filename": "string",
    "confirm_asset_upload": true
  }
});

result = await session.call_tool("discourse_upload_theme_asset", arguments={
  "file_data": "string",
  "file_path": "string",
  "filename": "string",
  "confirm_asset_upload": true
})

Parameters

file_datastring

file_pathstring

filenamestring

confirm_asset_uploadbooleanrequired

Delete Theme

destructiveopen-world

discourse_delete_theme

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 Theme

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_delete_theme",
    "arguments": {
        "theme_id": 0,
        "expected_theme_name": "string",
        "confirm_delete": true
      }
  }
}

const result = await client.callTool({
  "name": "discourse_delete_theme",
  "arguments": {
    "theme_id": 0,
    "expected_theme_name": "string",
    "confirm_delete": true
  }
});

result = await session.call_tool("discourse_delete_theme", arguments={
  "theme_id": 0,
  "expected_theme_name": "string",
  "confirm_delete": true
})

Parameters

theme_idintegerrequired

expected_theme_namestringrequired

confirm_deletebooleanrequired

Docs by Sourcey