Omarchy

A Model Context Protocol (MCP) server for integrating Omarchy desktop environment theme management with AI assistants like Claude.

Overview

Omarchy MCP enables AI assistants to manage themes in Omarchy - a Linux desktop environment that supports extensive theme customization including color schemes, backgrounds, and UI elements.

With this MCP server, AI assistants can:

• List themes with flexible filtering (installed, available, built-in, removable)
• Query the currently active theme
• Switch between installed themes
• Preview theme images before applying them
• Install new themes from GitHub repositories
• Remove installed extra themes
• Rotate background images

Youtube Video

Installation

Using in llms .py

Or paste server configuration into llms .py MCP Servers:

Name: omarchy-mcp

{
  "description": "Manage Omarchy Desktop Themes",
  "command": "uvx",
  "args": [
    "omarchy-mcp"
  ]
}

Development Server

For development, you can run this server using uv:

{
  "mcpServers": {
    {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/ServiceStack/omarchy-mcp",
        "omarchy-mcp"
      ]
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "omarchy": {
      "description": "Manage Omarchy Desktop Themes",
      "command": "uvx",
      "args": [
        "omarchy-mcp"
      ]
    }
  }
}

System Prompt

You can make your AI a more pleasant and personable Omarchy assistant by configuring it with a custom system prompt. The linked system prompt below creates "Archy" - a friendly, conversational assistant that knows Omarchy well and responds naturally to voice commands.

system-prompt.txt

Available Tools

omarchy_theme_list

Lists Omarchy themes with flexible filtering options.

Parameters:

• filter (optional): Filter themes by type
  • "INSTALLED" (default) - All installed themes
  • "ALL" - All available themes (installed and not installed)
  • "CURRENT" - Only the currently active theme
  • "BUILT_IN" - Only built-in themes
  • "CAN_REMOVE" - Only installed extra themes that can be removed
  • "CAN_INSTALL" - Only themes available for installation
• scheme (optional): Filter by color scheme
  • "ANY" (default) - All color schemes
  • "LIGHT" - Light themed only
  • "DARK" - Dark themed only

Returns: List of theme names with status indicators (current, built-in, installed)

omarchy_theme_set

Applies a theme to the Omarchy desktop.

Parameters:

• theme (required): Theme name to apply (supports partial/case-insensitive matching)

Returns: Preview image of the applied theme

omarchy_theme_bg_next

Rotates to the next background image in the current theme.

Returns: The new background image

omarchy_preview_theme

Downloads and returns a preview image for a theme without applying it.

Parameters:

• name (required): Theme name (supports partial/case-insensitive matching)

Returns: Theme preview image

omarchy_install_theme

Installs a new extra/community theme from its GitHub repository. Installing a theme automatically sets it as the current theme.

Parameters:

• name (required): Theme name to install

Returns: Theme preview image after installation

omarchy_remove_theme

Uninstalls a previously installed extra/community theme. Built-in themes cannot be removed.

Parameters:

• name (required): Theme name to uninstall

Returns: Status message

Theme Matching

Theme names support flexible matching:

• Case-insensitive: "tokyo night", "TOKYO NIGHT", and "Tokyo Night" all match
• Partial matching: "tokyo" matches "Tokyo Night"
• Punctuation-insensitive: "tokyo-night", "tokyo_night", and "tokyonight" all match

Requirements

• Python: 3.10, 3.11, or 3.12
• Omarchy: Must be installed on the system
• Linux: With Wayland display server

Dependencies

• fastmcp>=0.1.0 - MCP server framework
• aiohttp - Async HTTP client for downloading preview images

Built-in Themes

Omarchy comes with 14 built-in themes:

• Tokyo Night
• Catppuccin
• Ethereal
• Everforest
• Gruvbox
• Hackerman
• Osaka Jade
• Kanagawa
• Nord
• Matte Black
• Ristretto
• Flexoki Light
• Rose Pine
• Catppuccin Latte

Extra Themes

Over 100 additional community themes are available for installation, including various color schemes for both dark and light preferences.

Development

Setup

git clone https://github.com/ServiceStack/omarchy-mcp.git
cd omarchy-mcp
pip install -e ".[dev]"

Running Tests

pytest tests -v

Linting and Formatting

ruff check .
ruff format .

Building

python -m build

License

BSD-3-Clause