Skip to main content
Glama
RavaniRoshan

WinScript

by RavaniRoshan
OverviewSchemaRelated ServersScoreDiscussions
Python
Local
██╗    ██╗██╗███╗   ██╗███████╗ ██████╗██████╗ ██╗██████╗ ████████╗
██║    ██║██║████╗  ██║██╔════╝██╔════╝██╔══██╗██║██╔══██╗╚══██╔══╝
██║ █╗ ██║██║██╔██╗ ██║███████╗██║     ██████╔╝██║██████╔╝   ██║   
██║███╗██║██║██║╚██╗██║╚════██║██║     ██╔══██╗██║██╔═══╝    ██║   
╚███╔███╔╝██║██║ ╚████║███████║╚██████╗██║  ██║██║██║        ██║   
 ╚══╝╚══╝ ╚═╝╚═╝  ╚═══╝╚══════╝ ╚═════╝╚═╝  ╚═╝╚═╝╚═╝        ╚═╝

AppleScript for Windows. Built for AI agents.

Windows 10/11 · Python 3.10+ · MCP Protocol

Python MCP License Tools PyPI

macOS has AppleScript.
Windows had nothing clean for AI agents.
Until now.

WinScript is a state-aware, replayable, audited Windows automation server for AI agents. It wraps 4 fragmented Windows automation primitives — UI Automation, COM, Win32, and OCR — into a single MCP server that any agent can call.

Not a wrapper. Not a toy. Infrastructure.

Quick Start — Get WinScript Running in Claude Desktop

Option 1: Claude Desktop Extension (Easiest — Coming Soon)

Once approved in Claude's Extensions directory:

  1. Open Claude Desktop

  2. Go to Settings → Extensions

  3. Search for "WinScript"

  4. Click Install

  5. 59 tools appear — done!

Until then: Use Option 2 or 3 below.

Option 2: One-Click Installer

Step 1: Download this repo and double-click install.bat:

git clone https://github.com/RavaniRoshan/winscript-mcp.git
cd winscript-mcp

Then double-click install.bat (or run python install.py)

Step 2: Restart Claude Desktop

Step 3: WinScript appears in Claude's Extensions panel with 59 tools.

Option 3: PyPI (One Command)

pip install winscript
winscript

Then configure Claude Desktop manually (see below).

Option 4: Docker (Isolated)

docker run -v %USERPROFILE%/.winscript:~/.winscript ghcr.io/roshandamm/winscript-mcp:latest

Option 5: Direct from Source

git clone https://github.com/RavaniRoshan/winscript-mcp.git
cd winscript-mcp
pip install -r requirements.txt
python winscript-server.py

All options start an MCP server. The Claude Desktop Extension (Option 1) will be the easiest once approved.

The difference

Every other Windows automation tool gives you actions.
WinScript gives you actions + state.

# What others give you:
click("Submit")
→ "Clicked Submit"

# What WinScript gives you:
click("Submit")
→ "Clicked 'Submit' via uia_name [confidence 1.0] |
   Active window: 'Form' → 'Confirmation' |
   New windows: ['Success Dialog'] |
   Duration: 312ms"

You don't just know what you did. You know what changed.

Detailed Installation

Option 1: Install from PyPI

pip install winscript

Then run: winscript or python -m winscript.server

Option 2: Run with Docker

# Pull and run
docker run -d --name winscript \
  -v %USERPROFILE%/.winscript:~/.winscript \
  ghcr.io/roshandamm/winscript-mcp:latest

# Or build locally
docker build -t winscript:latest .
docker run -d --name winscript -v %USERPROFILE%/.winscript:~/.winscript winscript:latest

Option 3: Run from Source (No Install)

git clone https://github.com/roshandamm/winscript-mcp.git
cd winscript-mcp
pip install -r requirements.txt
python winscript-server.py

Optional: OCR Fallback (Layer 4)

For better element detection in broken UI trees:

# Install Tesseract: https://github.com/tesseract-ocr/tesseract
pip install pytesseract

How WinScript Appears in Claude Desktop

After running the installer and restarting Claude Desktop, WinScript appears in Claude's Extensions panel just like Desktop Commander:

┌─────────────────────────────────────────────┐
│  WinScript                                   │
│  AppleScript for Windows. Built for AI      │
│  agents. Control any Windows app from Claude │
│  Enabled                                     │
│                                              │
│  Developed by Roshan Ravani                  │
│                                              │
│  Tools                    59                 │
│  open_app                                   │
│  close_app                                  │
│  click                                      │
│  type_text                                  │
│  excel_read_cell                            │
│  outlook_send_email                         │
│  take_screenshot                            │
│  +53 more                                   │
│                                              │
│  Requirements                                │
│  All requirements met                        │
│                                              │
│  Details                                     │
│  Version         0.1.0                      │
│  License         MIT                         │
│  Author          Roshan Ravani              │
└─────────────────────────────────────────────┘

Claude can now:

  • Open and control any Windows app

  • Click buttons and type in UIs

  • Read/write Excel files via COM

  • Send Outlook emails

  • Take screenshots

  • Manage files and folders

  • Record and replay workflows

  • And 50+ more actions

All through natural language — no human interaction needed.

Wire into Claude Desktop

The easy way: Run install.bat — it configures everything for you.

The manual way: Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "winscript": {
      "command": "python",
      "args": ["-m", "winscript.server"]
    }
  }
}

Restart Claude Desktop. 59 tools appear automatically.

Five things that make WinScript different

1. Five-layer selector fallback chain

Other tools fail when the UI tree is bad (Electron apps, UWP, legacy Win32).
WinScript tries 5 strategies before giving up.

Layer 1 → UIA by element name       (fast, exact)
Layer 2 → UIA by automation_id      (for apps that label controls)
Layer 3 → UIA fuzzy role match      (partial name, control type)
Layer 4 → OCR scan + bounding box   (when UI tree is broken)
Layer 5 → Raw coordinates           (click("x=412,y=308"))

Every tool call tells you which layer succeeded:

"Clicked 'Login' in 'Slack' [via ocr, confidence 0.91]"

2. State diffing after every action

Before you act, WinScript snapshots the desktop.
After you act, it snapshots again and diffs.

# The agent knows what actually happened:
open_app("excel")
→ "Opened Excel | Active window: '' → 'Book1 - Excel' | 
   New windows: ['Microsoft Excel - Book1'] | Duration: 2140ms"

type_text("Notepad", "hello")
→ "Typed 5 chars | No window change detected | Duration: 89ms"

No more "did it work?" loops.

3. Workflow recorder and replay

Record any successful multi-step sequence. Replay it on demand.
No human-written macros. No brittle scripts.

# Record:
workflow_record_start("daily_report", "Opens report and emails it")
open_latest_file("C:/reports", "xlsx")
read_active_document()
send_email_with_content("team@co.com", "Daily Report", "clipboard")
workflow_record_stop()
→ "Workflow 'daily_report' saved: 3 steps"

# Replay any time:
workflow_replay("daily_report")
→ "Step 1 ✓ open_latest_file → Opened q1_2026.xlsx [2100ms]
   Step 2 ✓ read_active_document → [clipboard content] [340ms]
   Step 3 ✓ send_email_with_content → Email sent [890ms]"

# Preview before running:
workflow_replay("daily_report", dry_run=True)

4. Semantic intent layer

Five high-level intents so agents don't have to think in clicks.

open_latest_file("C:/reports", "xlsx")     # Find + open newest xlsx
send_email_with_content("a@b.com", "Re", "clipboard")  # Clipboard → email
find_in_folder("C:/docs", "invoice", "pdf")  # Find matching files
read_active_document()                      # Select-all copy current doc
summarize_screen()                          # Screenshot → agent vision

5. Full audit log + local memory

Every action, input, output, state delta, selector layer, and failure logged to ~/.winscript/audit.db.

get_audit_log(10)
→ "[14:23:01] ✓ open_app({'name':'notepad'}) → Opened notepad [2100ms]
   [14:23:03] ✓ type_text({'text':'hello'}) → Typed 5 chars [89ms]
   [14:23:11] ✗ click({'element':'Submit'}) → ERROR: No element found [412ms]"

get_failure_report()
→ "click: 3/12 failures (25%) | avg 380ms
   open_app: 0/8 failures (0%) | avg 2100ms"

And memory persists across sessions:

what_files_have_i_opened(5, "xlsx")
→ "C:/reports/q1_2026.xlsx — opened 4x | last: 14:23 08/04"

what_did_i_do(5)
→ "[14:23] open_app → Opened notepad
   [14:22] excel_read_cell → 47230.5
   [14:21] outlook_send_email → Email sent to team@co.com"

All 59 tools

Tool

What it does

open_app(name)

Open any app by name or alias

close_app(title_hint)

Close by partial window title

focus_app(title_hint)

Bring to foreground

get_running_apps()

List all open windows + PIDs

Tool

What it does

click(app_title, element_name)

Click element — 5-layer fallback

type_text(app_title, text)

Type into focused element

read_text(app_title, element_name)

Read text from element

press_key(key, app_title)

Keyboard shortcuts

get_ui_tree(app_title, depth)

Discover all UI elements

Tool

What it does

excel_read_cell(filepath, sheet, cell)

Read one cell

excel_write_cell(filepath, sheet, cell, value)

Write one cell + save

excel_read_range(filepath, sheet, start, end)

Read range as CSV

outlook_send_email(to, subject, body)

Send email

outlook_read_inbox(count)

Read N recent emails

read_file_text · write_file_text · list_dir · move_file · copy_file · delete_file · file_exists

Tool

What it does

take_screenshot(region)

Base64 PNG — agent sees your screen

get_active_window()

Current focused window title

get_clipboard()

Read clipboard

set_clipboard(text)

Write clipboard

Typed semantic APIs for specific apps. No more clicking blind.

# Excel
excel_open(filepath)  ·  excel_save()  ·  excel_close(save)

# Chrome
chrome_open(url)  ·  chrome_navigate(url)  ·  chrome_get_url()
chrome_get_title()  ·  chrome_new_tab()  ·  chrome_close_tab()
chrome_find_on_page(text)

# Notepad
notepad_open(filepath)  ·  notepad_type(text)
notepad_save()  ·  notepad_close(save)

# Explorer
explorer_open(path)  ·  explorer_navigate(path)

# Outlook
outlook_open()
workflow_record_start(name, description)
workflow_record_stop()
workflow_record_discard()
workflow_replay(name, dry_run)
workflow_list()
workflow_delete(name)
open_latest_file(folder, extension)
send_email_with_content(to, subject, content_source)
find_in_folder(folder, search_term, extension)
read_active_document()
summarize_screen()
# Audit
get_audit_log(limit, tool_filter)
get_failure_report()

# Memory
what_windows_have_i_seen(limit)
what_files_have_i_opened(limit, extension)
what_did_i_do(limit)

# State
get_state_snapshot()

# Modes
set_execution_mode(mode)   # "safe" | "standard"
get_execution_mode()

App aliases

open_app("notepad")    # notepad.exe
open_app("chrome")     # chrome.exe
open_app("firefox")    # firefox.exe
open_app("edge")       # msedge.exe
open_app("excel")      # EXCEL.EXE
open_app("word")       # WINWORD.EXE
open_app("outlook")    # OUTLOOK.EXE
open_app("explorer")   # explorer.exe
open_app("terminal")   # wt.exe
open_app("vscode")     # Code.exe
open_app("cursor")     # Cursor.exe

Error handling

Tools return "ERROR: ..." strings to the agent on failure — never crash your agent.

After 5 consecutive identical failures on the same tool + args:
WinScriptMaxRetriesError is raised. Hard stop. Change your args and try again.

get_failure_report()
# See which tools are failing and why before they hit the limit

Execution modes

set_execution_mode("safe")
# Read-only: screenshots, reads, audits only
# Blocks: write, delete, click, type, send email, open apps

set_execution_mode("standard")
# Full access (default)

Where recordings live

~/.winscript/
├── audit.db          # every action ever taken
├── memory.db         # windows, files, action history
└── workflows/
    ├── daily_report.json
    └── your_workflow.json

Auto-purge: audit logs older than 30 days are deleted on startup.

Limitations (honest)

  • Windows only. By design. This is not a bug.

  • Elevated (admin) apps cannot be automated from a non-admin process.

  • UWP + Electron apps have broken accessibility trees. WinScript falls back to OCR then coordinates — but complex UIs still sometimes fail.

  • Requires Tesseract for OCR fallback (Layer 4). Without it, WinScript skips to Layer 5.

  • COM automation (Excel, Outlook) requires those apps installed and licensed.

Built on

Layer

Library

MCP server

FastMCP

UI automation

pywinauto + uiautomation

COM automation

pywin32

OCR fallback

pytesseract + Tesseract

Screenshots

mss + Pillow

State + memory

SQLite

Docker

# Pull from GitHub Container Registry
docker run -d --name winscript -v ${HOME}/.winscript:/root/.winscript ghcr.io/roshandamm/winscript-mcp:latest

# Or build from source
git clone https://github.com/RavaniRoshan/winscript-mcp.git
cd winscript-mcp
docker build -t winscript:latest .
docker run -d --name winscript -v winscript_data:/root/.winscript winscript:latest

# Using Docker Compose
docker-compose up -d

Build Claude Desktop Extension

# Windows: Double-click build-extension.bat
# Linux/Mac: ./build-extension.sh

This creates winscript.mcpb - a one-click installable extension for Claude Desktop.

Test locally: Double-click the .mcpb file → Claude Desktop opens → review → install

Developer Commands

# Build package
pip install build && python -m build

# Install locally
pip install -e .

# Run tests
pip install pytest && pytest tests/ -v

# Connect to Cursor
# Edit .cursor/mcp.json:
{"mcpServers": {"winscript": {"command": "python", "args": ["-m", "winscript.server"]}}}

Examples

Screenshot + Vision Fallback

For legacy apps with broken UI trees:

  1. open_app("Legacy Inventory")

  2. take_screenshot() → pass to Claude Vision

  3. coordinate_click(x, y) to click visually located element

Excel to Email Workflow

  1. excel_read_range("report.xlsx", "Sheet1", "A1:D10")

  2. outlook_send_email("team@company.com", "Daily Report", body)

File Triage

  1. list_dir("C:/Downloads")

  2. move_file("file.pdf", "C:/Documents/")

Troubleshooting

"Server disconnected" errors:

  • Ensure PYTHONPATH is set correctly in Claude Desktop config

  • Check Python path is valid

"Module not found: winscript":

  • Run python winscript-server.py from the project root

  • Or use pip install -e . to install the package

COM automation fails (Excel/Outlook):

  • Ensure Microsoft Office is installed and licensed

  • Run as administrator for first-time COM registration

UI elements not found:

  • Try increasing timeout: wait_for_window("App Name", timeout_seconds=30)

  • Enable OCR fallback: install Tesseract and pip install pytesseract

License

MIT

WinScript — 59 tools. State-aware. Replayable. Audited. Memory-backed.

Built by Roshan Ravani

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/RavaniRoshan/winscript-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server