sys-tools

ltcg-addict/sys-tools

3.2

If you are the rightful owner of sys-tools and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The System Tools MCP Server is a powerful tool that allows AI assistants to control the graphical user interface of a computer, including mouse and keyboard actions.

Tools
6
Resources
0
Prompts
0

System Tools MCP Server

A Model Context Protocol (MCP) server that interacts with the desktop GUI to control the mouse and keyboard.

⚠️ SECURITY WARNING ⚠️

This server provides powerful tools to control your computer's graphical user interface. It can move the mouse, click, and type. Enabling this server gives the AI assistant significant control over your machine. USE WITH EXTREME CAUTION. Only enable this tool if you fully understand the risks involved.

Purpose

This MCP server provides a secure interface for AI assistants to perform GUI automation tasks like moving the mouse, clicking buttons, and typing text.

Features

Current Implementation

  • get_screen_size - Returns the current screen resolution (width and height).
  • mouse_move - Moves the mouse to the specified X and Y coordinates.
  • mouse_click - Performs a mouse click with the specified button (left, right, middle).
  • mouse_scroll - Scrolls the mouse wheel up or down.
  • key_type - Types the provided text string.
  • key_press - Presses a special key or a sequence of keys (e.g., 'enter', 'ctrl-c').

Prerequisites

  • Docker Desktop with MCP Toolkit enabled
  • Docker MCP CLI plugin (docker mcp command)
  • An X11-based windowing system (common on Linux desktops). This server is not compatible with Wayland without additional configuration (e.g., XWayland).

Installation

See the step-by-step instructions provided with the files. Special configuration is required to allow the Docker container to access your display.

Usage Examples

In Claude Desktop, you can ask:

  • "What is the screen size?"
  • "Move the mouse to the center of the screen."
  • "Click the right mouse button."
  • "Scroll down a bit."
  • "Type the words 'Hello, world!'"
  • "Press the enter key."

Architecture

Claude Desktop → MCP Gateway → System Tools MCP Server → Host Display (X11)

Development

Local Testing

To test the server directly without the full MCP gateway, you can run it from your terminal. This requires you to have python and the libraries from requirements.txt installed locally.

# Run directly
python sys-tools_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python sys-tools_server.py

Adding New Tools

  1. Add the function to sys-tools_server.py
  2. Decorate with @mcp.tool()
  3. Update the catalog entry with the new tool name
  4. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

  • Verify Docker image built successfully.
  • Check your custom.yaml and registry.yaml files for correct entries.
  • Ensure Claude Desktop config includes the custom.yaml catalog.
  • Restart Claude Desktop completely.

GUI Commands Fail

  • CRITICAL: Ensure you have modified your claude_desktop_config.json to share your display with the Docker container as described in the installation instructions.
  • Verify you are running an X11 session. Run echo $XDG_SESSION_TYPE in a terminal. If it says wayland, these tools may not work.
  • Check the server logs for errors: docker logs <container_name>

Security Considerations

  • HIGH RISK: This tool grants the AI control over your GUI.
  • The server runs as a non-root user inside the container.
  • No sensitive data is logged.

License

MIT License