Add Omarchy MCP

Author: mythz

app/(home)/page.tsx

@@ -164,7 +164,7 @@ export default function HomePage() {
               </Card>
             </Link>
 
-            <Link href="/docs/extensions/fast_mcp" className="block">
+            <Link href="/docs/mcp/fast_mcp" className="block">
               <Card className="bg-white dark:bg-slate-900 border-slate-200 dark:border-slate-700 hover:border-blue-400 dark:hover:border-blue-500 transition-colors cursor-pointer h-full">
                 <CardHeader>
                   <CardTitle className="flex items-center gap-2 text-slate-900 dark:text-slate-100">
@@ -463,7 +463,7 @@ export default function HomePage() {
               Extend LLM capabilities with Model Context Protocol servers
             </p>
             <Link
-              href="/docs/extensions/fast_mcp"
+              href="/docs/mcp/fast_mcp"
               className="inline-flex items-center gap-1 text-blue-600 dark:text-blue-400 hover:underline mt-2"
             >
               Learn more →

content/docs/mcp/omarchy_mcp.mdx

@@ -0,0 +1,206 @@
+---
+title: Omarchy MCP
+description: Omarchy MCP enables AI assistants to manage themes in Omarchy
+---
+
+A Model Context Protocol (MCP) server for integrating [Omarchy](https://omarchy.org) desktop environment theme management with AI assistants like Claude.
+
+<iframe
+  width="560"
+  height="315"
+  src="https://www.youtube.com/embed/eV17C0cJz00"
+  title="YouTube video player"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowFullScreen
+></iframe>
+
+[Youtube Video](https://youtu.be/eV17C0cJz00?si=eGDeEL2d6KLddGBj)
+
+## 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.
+
+<Screenshot src="/img/mcp/omarchy-mcp/tools_omarchy_theme_list.webp" />
+
+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
+
+## Installation
+
+### Using in llms .py
+
+Paste server configuration into [llms .py MCP Servers](/docs/mcp/fast_mcp):
+
+Name: `omarchy-mcp`
+
+```json
+{
+  "description": "Manage Omarchy Desktop Themes",
+  "command": "uvx",
+  "args": [
+    "omarchy-mcp"
+  ]
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration file:
+
+```json
+{
+  "mcpServers": {
+    "omarchy": {
+      "description": "Manage Omarchy Desktop Themes",
+      "command": "uvx",
+      "args": [
+        "omarchy-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Development Server
+
+For development, you can run this server using `uv`:
+
+```json
+{
+  "mcpServers": {
+    {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/ServiceStack/omarchy-mcp",
+        "omarchy-mcp"
+      ]
+    }
+  }
+}
+{
+  "command": "uv",
+  "args": [
+    "run",
+    "--directory",
+    "/home/mythz/src/ServiceStack/omarchy-mcp",
+    "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](https://github.com/ServiceStack/omarchy-mcp/blob/main/src/omarchy_mcp/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.

content/docs/meta.json

@@ -8,8 +8,9 @@
     "multimodal",
     "media-generation",
     "extensions",
-    "configuration",
+    "mcp",
     "cli",
+    "configuration",
     "deployment"
   ]
 }

content/docs/v3.mdx

@@ -499,7 +499,24 @@ Tool outputs containing HTML content are rendered within a sandboxed iframe, let
 
 <Screenshot src="/img/tools/tools-chat-tetris.webp" />
 
-See the [MCP Support](/docs/extensions/fast_mcp) docs for complete configuration and usage details.
+See the [MCP Support](/docs/mcp/fast_mcp) docs for complete configuration and usage details.
+
+### Omarchy MCP
+
+For [Omarchy](https://omarchy.org) users, the [Omarchy MCP](/docs/mcp/omarchy_mcp) enables AI assistants to manage themes - including listing, switching, previewing, installing, and removing themes from your Omarchy desktop environment.
+
+<iframe
+  className="my-4"
+  width="560"
+  height="315"
+  src="https://www.youtube.com/embed/eV17C0cJz00"
+  title="YouTube video player"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowFullScreen
+></iframe>
+
+<Screenshot src="/img/mcp/omarchy-mcp/tools_omarchy_theme_list.webp" />
 
 ## Core Tools