GachaMCP Server

You are setting up and using GachaMCP, a Python-based MCP Server that lets an AI interact with a Gacha game through screenshots and click automation. It manages game windows, captures screenshots, performs clicks at coordinates, waits for smart delays, and tracks game state to enable reliable automation.

How to use

To use the GachaMCP server, run it in stdio mode from a development or integration environment, then connect your MCP client to the server. The server exposes tools to locate the game window, capture screenshots, click at precise positions, wait for conditions, and examine window information. You can also manage focus and iterate through screenshots to enable the AI to analyze and act based on the game state.

Common workflow patterns you will follow include finding the game window, capturing a screenshot, analyzing the image, performing a click, and waiting for the next state. You can chain these actions to implement robust automation flows for tasks like performing a Gacha pull, navigating menus, or confirming in-game results.

How to install

Prerequisites: you need Python installed and a suitable environment manager. This guide uses a virtual environment to isolate dependencies.

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# Linux/macOS
source venv/bin/activate

# Windows
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Additional notes

Development and integration modes are provided as stdio commands. You can start in development mode or install for Claude Desktop integration. Screenshots are stored in the screenshots/ directory with timestamped filenames for easy reference and later analysis.

Tools exposed by the server include a range of helpers to locate and interact with the game window, capture screens, perform clicks, and inspect window information. Use them to build reliable automation sequences that your AI can execute against the game UI.

Tool usage examples

You can script typical automation steps as follows (conceptual sequence): find the game window, capture a screenshot, analyze the image, click at a position, wait and capture again.

Available tools

find_game_window

Find the game window by name to target the correct window for screenshot capture and input events.

capture_game_screen

Capture the window contents and save a screenshot file for AI analysis.

click_at_position

Perform a click at specific (x, y) coordinates within the game window.

wait_and_capture

Wait for a specified delay and capture a new screenshot to observe the updated state.

get_window_info

Retrieve information about the game window, such as size and position.

focus_game_window

Bring the game window into focus to ensure input events are directed correctly.

list_all_windows

List all currently available windows to help you locate the target game window.

get_last_screenshot

Return the path to the most recent screenshot captured.

list_screenshots

List all saved screenshots in the storage directory.

clear_screenshots

Delete all saved screenshots to reclaim space and keep logs tidy.