Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@omarchy-mcp switch to Tokyo Night theme"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for integrating Omarchy desktop environment theme management with AI assistants like Claude.
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
Related MCP server: Linux System MCP Server
Or paste server configuration into llms .py MCP Servers:
Name: omarchy-mcp
{
"description": "Manage Omarchy Desktop Themes",
"command": "uvx",
"args": [
"omarchy-mcp"
]
}For development, you can run this server using uv:
{
"mcpServers": {
{
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/ServiceStack/omarchy-mcp",
"omarchy-mcp"
]
}
}
}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"
]
}
}
}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.
omarchy_theme_listLists 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_setApplies 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_nextRotates to the next background image in the current theme.
Returns: The new background image
omarchy_preview_themeDownloads 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_themeInstalls 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_themeUninstalls a previously installed extra/community theme. Built-in themes cannot be removed.
Parameters:
name (required): Theme name to uninstall
Returns: Status message
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
Python: 3.10, 3.11, or 3.12
Omarchy: Must be installed on the system
Linux: With Wayland display server
fastmcp>=0.1.0 - MCP server framework
aiohttp - Async HTTP client for downloading preview images
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
Over 100 additional community themes are available for installation, including various color schemes for both dark and light preferences.
git clone https://github.com/ServiceStack/omarchy-mcp.git
cd omarchy-mcp
pip install -e ".[dev]"pytest tests -vruff check .
ruff format .python -m buildBSD-3-Clause
Install an Omarchy extra theme by name. Installing a theme automatically sets it as the current theme.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries burden. It discloses the important behavioral trait that installation also sets the theme as current, but omits details like failure modes or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no wasted words. Front-loaded with key action and consequence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-param tool with no output schema or annotations, description covers purpose and one side effect but lacks success/failure behavior or context about 'extra theme'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description only says 'by name', which adds minimal meaning beyond the parameter name. No info on valid names, format, or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'install' and resource 'Omarchy extra theme', with the key side effect of automatically setting it as current. Distinguishes from siblings like omarchy_remove_theme or omarchy_preview_theme.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to install vs. other theme tools (e.g., omarchy_theme_set). Does not mention prerequisites or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a preview image for an Omarchy theme by name.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states a read-like operation but does not discuss error handling, resource limitations, or side effects (e.g., if theme name is invalid).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence) and front-loaded, but it lacks substantive detail that would justify its brevity. It is not overly verbose, but could be improved by adding context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should explain what the preview image looks like or how it is returned. It does not, leaving the agent unsure of the output type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must add meaning. It only says 'by name', which is already implied by the parameter name 'name'. No format, constraints, or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'preview image for an Omarchy theme', and includes the mechanism 'by name'. It is distinct from sibling tools which involve installing, removing, listing, or setting themes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, context, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Uninstall an Omarchy extra theme by name. Built-in themes cannot be removed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Discloses that built-in themes cannot be removed, but lacks details on side effects, error handling, or success behavior for a destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence front-loaded with the action. No wasted words; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the core purpose and a key constraint. Could mention behavior when theme name is invalid or currently active, but minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, requiring description to compensate. Description only says 'by name', which is already evident from the schema's required string parameter. No format, constraints, or examples provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Uninstall' and resource 'Omarchy extra theme by name', distinguishing from sibling tools (install, preview, list, set). Inclusion of 'Built-in themes cannot be removed' adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states that built-in themes cannot be removed, providing a clear exclusion. Context implies use for extra themes only, but does not explicitly compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cycle to the next Omarchy theme background.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'cycle to the next' without disclosing behavior like wrapping, state changes, or confirmation. Essential behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler, direct and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is minimally adequate but lacks details like looping behavior or visual feedback.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. The description explains what the tool does, which adds value beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool cycles to the next Omarchy theme background, with a specific verb ('cycle') and resource. It distinguishes from sibling tools like install, remove, or set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives like 'set'. The agent is not told that this is for sequential cycling and may be preferred for quick previews.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of Omarchy themes.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | installed | |
| scheme | No | any |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose any behavioral details such as side effects, return format, or filtering behavior. It only states 'Get a list' without further elaboration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 5 words, which is very concise but lacks structure. It could be improved by front-loading key details while remaining brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two optional parameters, an output schema, and no annotations, the description is incomplete. It omits filtering capabilities, default values, and any description of the output, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'filter' or 'scheme' parameters. It adds no value beyond the schema's enum values, which lack descriptions themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a list of Omarchy themes' clearly states the verb (get) and resource (list of themes), and distinguishes from sibling tools like install, preview, remove, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives. The description does not mention context or exclusions for filtering, and sibling tools are listed but not explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the current Omarchy theme.
| Name | Required | Description | Default |
|---|---|---|---|
| theme | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says 'Set the current Omarchy theme' without mentioning side effects, persistence, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks essential detail. It is too terse for an adequate tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a single undocumented parameter, the description leaves too many gaps. It does not explain the effect or how to revert the action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the 'theme' parameter (0% coverage). The description does not add any information about valid values, format, or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Set) and the resource (current Omarchy theme). It distinguishes itself from sibling tools like install, preview, remove, and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no explanation of prerequisites or context for setting a theme.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.0.6omarchy_install_themeomarchy_preview_themeomarchy_remove_themeomarchy_theme_bg_nextomarchy_theme_listomarchy_theme_setEach tool targets a distinct action on themes: install, preview, remove, cycle background, list, and set. There is no overlap or ambiguity; an agent can clearly distinguish when to use each.
All tools use snake_case with a consistent 'omarchy_' prefix. Most follow a verb_noun pattern (e.g., install_theme, preview_theme), though 'theme_bg_next' and 'theme_list' slightly deviate from the order. Overall, the pattern is clear and predictable.
Six tools is well-scoped for a theme management server. Each tool serves a necessary function without redundancy, covering installation, removal, listing, setting, previewing, and background cycling.
The tool set covers the main lifecycle of themes: install, remove, list, set, preview, and background control. A minor gap is the lack of an explicit 'get current theme' tool, but that may be inferred from the set action. Overall, it is sufficiently complete for typical theme management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Search Tailwind CSS and React themes, read their tokens and source files, and get download URLs.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ServiceStack/omarchy-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
