How do I use tkinter-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tkinter-mcp-server launch the calculator app and click the '7' button" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

tkinter-mcp-server

by tctibbs

Overview Schema Source Related Servers Discussions Admin

Python

Local

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.

Demo

Related MCP server: qt-mcp

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

Available Tools

16 tools

click_widgetA

Click a widget by its ID.

Finds the widget with the given ID and triggers a click action. For buttons, this invokes the button command. For other widgets, this generates a click event.

Inputs: widget_id (required), button, double. Returns: result

close_appA

Close the currently running Tkinter application.

Terminates the app gracefully.

Returns: JSON with success status

Inputs: no named parameters. Returns: result

drag_widgetA

Perform drag and drop between two widgets.

Simulates dragging from one widget to another. Useful for drag-and-drop interfaces like chess boards, sortable lists, etc.

Inputs: start_widget_id (required), end_widget_id (required). Returns: result

focus_widgetA

Set keyboard focus to a widget.

Inputs: widget_id (required). Returns: result

get_focused_widgetA

Get the currently focused widget.

Returns: JSON with the focused widget's ID or null if no widget has focus

Inputs: no named parameters. Returns: result

get_ui_layoutA

Get the current UI layout as hierarchical JSON.

Returns a JSON structure containing the complete widget tree with:

widget class names (Button, Label, Frame, etc.)
unique widget IDs
geometry (x, y, width, height)
widget state (normal, disabled)
text content where applicable
nested children

Use this to understand the current state of the GUI.

Inputs: no named parameters. Returns: result

get_widget_by_textB

Find a widget by its text content.

Searches the widget tree for a widget containing the specified text. Returns the widget ID if found.

Inputs: text (required). Returns: result

get_widget_optionsB

Get available options for a Combobox or Listbox widget.

Returns the list of selectable options/items.

Inputs: widget_id (required). Returns: result

get_widget_valueA

Get the value of a widget based on its type.

Returns the appropriate value for the widget type:

Entry/Text: text content
Scale: numeric value
Combobox: selected text
Checkbutton: boolean (checked/unchecked)
Radiobutton: variable value
Listbox: list of selected item texts
Spinbox: current value

Inputs: widget_id (required). Returns: result

get_window_infoA

Get basic information about the application window.

Returns JSON with window position and dimensions:

x, y: Window position on screen
width, height: Window dimensions in pixels

Useful for understanding window placement.

Inputs: no named parameters. Returns: result

is_connectedA

Check if an app is currently connected.

Returns: JSON with connection status

Inputs: no named parameters. Returns: result

launch_appA

Launch a Tkinter application with inspection enabled.

Starts the script with automatic Tkinter patching. The app will be inspectable via the other tools once launched.

Inputs: script_path (required). Returns: result

set_widget_valueA

Set the value of a widget based on its type.

Sets the appropriate value for the widget type:

Entry/Text: sets text content
Scale: sets numeric value (e.g., "50.0")
Combobox: sets selected text
Checkbutton: sets checked state ("true"/"false")
Radiobutton: selects this radio button (value ignored)
Listbox: selects item by index (e.g., "0", "1")
Spinbox: sets value

Inputs: widget_id (required), value (required). Returns: result

type_textA

Type text into an Entry or Text widget.

Clears the current content and inserts the new text. Only works with Entry and Text widgets.

Inputs: widget_id (required), text (required). Returns: result

view_applicationA

Take a screenshot of the application window.

Returns a base64-encoded JPEG image of the current window state. Use this to visually inspect the GUI appearance.

Inputs: max_size, quality. Returns: result

view_application_thumbnailA

Take a small thumbnail screenshot of the application window.

Returns a low-resolution preview for quick UI state checks. Use view_application for detailed inspection.

Returns: Base64-encoded JPEG string prefixed with data URI scheme.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A3.9/5.0

Scored 2026-06-09 20:46 across 16 tools

Disambiguation5/5

Each tool has a distinct purpose: launching, clicking, dragging, focusing, getting UI layout, reading/writing widget values, etc. Even similar tools like view_application and view_application_thumbnail are differentiated by resolution.

Naming Consistency4/5

Tools mostly follow a verb_noun pattern (launch_app, click_widget, set_widget_value) or get_ prefix (get_widget_value, get_window_info). The mix is consistent within subgroups, but not strictly uniform across all tools.

Tool Count4/5

16 tools is slightly above the ideal range of 3-15, but the count is justified by the need for various GUI interactions and inspections. It does not feel excessive for the scope.

Completeness4/5

Covers core GUI operations: launch, close, click, drag, focus, read layout, read/write values, type text, and screenshots. Missing advanced interactions (e.g., right-click, scroll) but sufficient for fundamental testing.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
https://api.anotherai.dev/mcp
mcp-server
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
https://mcp.niftypm.com/mcp
Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
Fensory
com.fensory
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Finance Cryptocurrency Blockchain
1
https://mcp.fensory.com/mcp

Related MCP Servers

PyMCPAutoGUI
OS Automation App Automation
kitfactory
A
license
Not graded
quality
D
maintenance
An MCP server that bridges AI agents with GUI automation capabilities, allowing them to control mouse, keyboard, windows, and take screenshots to interact with desktop applications.
Updated 2 years ago (2025-03-30 10:54 UTC)
23
MIT
qt-mcp
Developer Tools App Automation Testing & QA Tools
0xCarbon
A
license
A
quality
D
maintenance
An MCP server for inspecting, debugging, and interacting with PySide6 desktop applications. It enables AI agents to capture UI snapshots, read widget properties, and perform actions like clicking buttons or typing text.
Updated 4 months ago (2026-07-24 07:43 UTC)
22
3
Apache 2.0
textual-mcp-server
Testing & QA Tools Developer Tools
discohead
A
license
A
quality
D
maintenance
An MCP server that lets AI agents launch, interact with, and inspect Textual TUI applications headlessly.
Updated 9 months ago (2026-02-17 07:28 UTC)
12
4
MIT
windows-computer-use-mcp
App Automation OS Automation
betrayzl
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI agents human-like control over Windows via visual perception and simulated mouse and keyboard input, enabling automation of any application without APIs.
Updated 6 months ago (2026-05-03 10:15 UTC)
41 npm
4
MIT

tkinter-mcp

Overview

Tools

Installation

uvx (Quick Start)

pip (Recommended for PIL apps)

Claude Desktop

How It Works

Requirements

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

PyMCPAutoGUI

qt-mcp

textual-mcp-server

windows-computer-use-mcp