tkinter-mcp

MCP server for inspecting and automating Tkinter GUI applications.

Overview

An MCP server that enables AI agents to launch, inspect, and interact with Tkinter applications. The server auto-injects an inspection agent via monkey-patching. No modifications to target apps required.

Tools

Tool	Description
launch_app	Start a Tkinter app with inspection enabled
is_connected	Check if an app is currently connected
get_ui_layout	Get the widget tree as structured JSON
view_application	Capture a high-quality JPEG screenshot
view_application_thumbnail	Capture a small thumbnail screenshot
get_window_info	Get window position and dimensions
click_widget	Click a widget (left/right/middle, single/double)
type_text	Type text into Entry or Text widgets
get_widget_by_text	Find a widget by its text content
focus_widget	Set keyboard focus to a widget
get_focused_widget	Get the currently focused widget
get_widget_value	Get widget value (Entry, Text, Scale, Checkbox, etc.)
set_widget_value	Set widget value based on widget type
get_widget_options	Get options for Combobox or Listbox
drag_widget	Drag and drop between two widgets
close_app	Terminate the application

Installation

uvx (Quick Start)

claude mcp add tkinter-mcp-server -- uvx tkinter-mcp-server

Note: Apps using PIL/ImageTk may have compatibility issues with uvx. Use pip install instead.

pip (Recommended for PIL apps)

pip install tkinter-mcp-server
claude mcp add tkinter-mcp-server -- tkinter-mcp-server

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "tkinter": {
      "command": "tkinter-mcp-server"
    }
  }
}

For uvx: use "command": "uvx" with "args": ["tkinter-mcp-server"]

How It Works

The server launches Tkinter apps through a custom launcher that patches tkinter.Tk.__init__. This injects an agent that communicates over a local socket, enabling thread-safe inspection and control of the GUI.

flowchart LR
    A[MCP Client] <--> B[MCP Server]
    B <--> C[Socket]
    C <--> D[Agent]
    D <--> E[Tkinter App]

Requirements

• Python 3.10+
• macOS, Windows, or Linux

License

MIT