Metadata-Version: 2.4
Name: tkinter-mcp-server
Version: 0.9.2
Summary: MCP server for inspecting and automating Tkinter GUI applications
Project-URL: Homepage, https://github.com/tctibbs/tkinter-mcp-server
Project-URL: Repository, https://github.com/tctibbs/tkinter-mcp-server
Project-URL: Issues, https://github.com/tctibbs/tkinter-mcp-server/issues
Author: Tristan Tibbs
License: MIT
License-File: LICENSE
Keywords: ai-agents,claude,gui-automation,llm,mcp,model-context-protocol,tkinter
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pyautogui>=0.9.54
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# tkinter-mcp

MCP server for inspecting and automating Tkinter GUI applications.

[![PyPI](https://img.shields.io/pypi/v/tkinter-mcp-server.svg)](https://pypi.org/project/tkinter-mcp-server/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)

## 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.

![Demo](assets/demo.gif)

## 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

### Claude Code

```bash
claude mcp add tkinter-mcp-server -- uvx tkinter-mcp-server
```

### Claude Desktop

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

```json
{
  "mcpServers": {
    "tkinter": {
      "command": "uvx",
      "args": ["tkinter-mcp-server"]
    }
  }
}
```

### pip

```bash
pip install 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.

```mermaid
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
