Hyprmcp MCP Server Integration

What does “Hyprmcp” MCP Server do?

Hyprmcp is a lightweight, unofficial Model Context Protocol (MCP) server that exposes the full functionality of hyprctl, the command-line interface for the Hyprland Wayland compositor, to language models. By integrating with Hyprmcp, AI assistants can query and control Hyprland’s window management, layouts, inputs, and more, using natural language. This enhances developer and user workflows by allowing tasks such as retrieving workspace information, managing monitors, running arbitrary Hyprland commands, and obtaining system state—all through a conversational AI interface. The server is designed to be experimental and in beta, providing a bridge between Hyprland’s rich command set and modern language model-driven interfaces.

List of Prompts

No prompt templates are mentioned in the available documentation or repository files.

List of Resources

No explicit MCP resources are documented in the repository or README.

List of Tools

• run_hyprctl_command
  Executes arbitrary hyprctl commands.
• get_version
  Retrieves the Hyprland version and build info.
• list_monitors
  Lists all connected monitors and their properties.
• list_workspaces
  Lists all active workspaces.
• list_clients
  (No description provided, but likely lists Hyprland clients/windows.)

Use Cases of this MCP Server

• Window Management via AI
  Enables AI assistants to control and query Hyprland windows, layouts, and workspaces, streamlining desktop organization tasks.
• Automated System Status Queries
  Developers can use natural language to check monitor configurations, active workspaces, and client windows, aiding diagnostics and scripting.
• Version and Environment Auditing
  Retrieve Hyprland version/build information for troubleshooting or documentation via AI queries.
• Integration with Dev Tools
  Seamlessly integrate Hyprland control into MCP-compatible clients (e.g., Claude, Cursor) for developer automation.
• Custom Workflow Automation
  Use arbitrary hyprctl commands through conversational interfaces for advanced, repeatable setups and workflows.

How to set it up

Windsurf

No setup instructions or configuration examples are provided for Windsurf.

Claude

1. Clone the Repository
   • git clone https://github.com/stefanoamorelli/hyprmcp.git
   • cd hyprmcp
2. Grab your HYPRLAND_INSTANCE_SIGNATURE
   • echo $HYPRLAND_INSTANCE_SIGNATURE
3. Edit Configuration
   • Open ~/.config/Claude/claude_desktop_config.json
4. Add Hyprmcp MCP Server
   • Insert the following JSON snippet:

     "Hyperland MCP Server": {
       "command": "uv",
       "args": [
         "run",
         "--with",
         "mcp[cli]",
         "--with",
         "subprocess",
         "mcp",
         "run",
         "<global path of the repo>/hyprmcp/hyprmcp/server.py"
       ],
       "env": {
         "PYTHONPATH": "<global path of the repo>/hyprmcp",
         "HYPRLAND_INSTANCE_SIGNATURE": "<your-hyprland-instance-signature>"
       }
     }
     

5. Save and Restart
   • Save the file and restart Claude Desktop to apply changes.

Securing API Keys

Use environment variables in the env section:

"env": {
  "HYPRLAND_INSTANCE_SIGNATURE": "<your-hyprland-instance-signature>"
}

Cursor

No setup instructions or configuration examples are provided for Cursor.

Cline

No setup instructions or configuration examples are provided for Cline.

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{
  "hyprmcp": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change “hyprmcp” to the actual name of your MCP server and replace the URL with your own server URL.

Overview

Our opinion

Hyprmcp provides a focused, useful bridge between Hyprland and MCP clients, with clear tooling and setup for at least one major platform. However, it lacks prompt templates, explicit resource definitions, and broader setup/platform support. As an experimental project, it’s a solid starting point for power users and developers, but would benefit from expanded documentation and resource support.

MCP Score

RATING: 5/10
Solid on basics (tools, license, core function), but lacks in prompt/resource documentation and multi-platform setup details.