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
1 maintainer
Metadata
1 maintainer
Release files for tkinter-mcp-server 0.9.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tkinter_mcp_server-0.9.3.tar.gz | 2.7 MB | With provenance | Details for tkinter_mcp_server-0.9.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tkinter_mcp_server-0.9.3-py3-none-any.whl | Python 3 | none | any | Details for tkinter_mcp_server-0.9.3-py3-none-any.whl |
Total release size: 2.7 MB
Release files / tkinter_mcp_server-0.9.3.tar.gz
| Download URL | tkinter_mcp_server-0.9.3.tar.gz |
|---|---|
| Size | 2.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3217ae705486ef8f993a78cb4b40b9ce47ea012bed3087d1746c63dbdaaa993b
|
|
BLAKE2b-256 checksum How to use checksums |
e89ef175b8da929b71fac66efd8d91d23f0d645037a82a5589cc333761e34ac3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 28, 2025.
Transparency logRelease files / tkinter_mcp_server-0.9.3-py3-none-any.whl
| Download URL | tkinter_mcp_server-0.9.3-py3-none-any.whl |
|---|---|
| Size | 24.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cddf2757affb0b2c4690b24055159d923bbfe7356ccefaffe028300f1ee3b40f
|
|
BLAKE2b-256 checksum How to use checksums |
6e6ed6ce9d8016983d3eb5a62959828f51d2e49348bc70e5a5d754ee2cb46c5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 28, 2025.
Transparency logSecurity for tkinter-mcp-server 0.9.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for tkinter_mcp_server-0.9.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 28, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
