playbooks

home / mcp / localplay mcp server

Localplay MCP Server

Provides a local MCP server that enables mouse control via move, click, drag, and scroll actions.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "hfyydd-localplay-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/localplay-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

You can run a local MCP server that handles mouse control commands, enabling you to move the cursor, click, drag, and scroll programmatically from a client. This is useful for automation, testing, or accessibility tooling where direct programmatic control of the mouse is needed.

How to use

To control the local MCP server from a client, connect via the MCP protocol and issue mouse actions such as move, click, drag, and scroll. The server translates your requests into real mouse movements and actions on the host machine. Use an MCP client that supports the available mouse control endpoints, then observe the results on the local desktop.

How to install

Install the dependencies required to run the local MCP server. You have two options depending on your preference for package management.

uv add "mcp[cli]" pyautogui
pip install "mcp[cli]" pyautogui

Starting the server

Start the MCP development server using the local project path. This will launch the server so you can begin sending MCP commands for mouse control.

"localplay-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/localplay-mcp-server",
        "run",
        "server.py"
      ]
    }

Using Docker

If you prefer containerized deployment, you can build and run a Docker image for the MCP server.

# Build the Docker image
docker build -t localplay-mcp-server .

# Run the Docker container
docker run -p 8080:8080 localplay-mcp-server

Server features

The server currently implements the following mouse control features: move the mouse to a specified coordinate, perform a mouse click at the current or a given position, drag from one position to another, and scroll the mouse wheel.

Usage examples

  • Move the mouse to specified coordinates, e.g. (100, 200)
  • Click at the current or a specified position
  • Drag from a starting position to a target position
  • Scroll up or down

Notes

Prepare your client application to send the appropriate MCP commands and handle responses. Ensure the host machine grants the necessary permissions for programmatic mouse control.

License

This project is open-sourced under the MIT License. See the LICENSE file for details.

Available tools

Move Mouse

Move the mouse cursor to a specified coordinate position on the screen.

Mouse Click

Click the left mouse button at the current or a specified position.

Mouse Drag

Drag the mouse from a starting position to a target position.

Mouse Scroll

Scroll the mouse wheel up or down.