Claude Pascal MCP Server

An MCP (Model Context Protocol) server that lets Claude compile, run, and interact with Pascal/Delphi desktop applications. Supports Free Pascal (fpc), Delphi 32-bit (dcc32), and Delphi 64-bit (dcc64) compilers.

Features

• Compiler Detection — automatically finds Pascal compilers on your system (PATH + known install locations)
• Compile — compile single-file Pascal source or multi-file Delphi projects
• Run — compile and execute console programs, capturing output
• Launch GUI Apps — compile and launch VCL/FMX applications in background (without stealing focus)
• Project Templates — generate proper Delphi project structure (DPR + PAS + DFM) automatically
• Form Parser — read and understand DFM/FMX/LFM form files
• Window Screenshots — capture running desktop app windows (non-intrusive, no focus stealing)
• Windows App Interaction — click, type text, and send keyboard shortcuts to desktop app windows
• Android Device Interaction — full ADB support: screenshots, tap, swipe, type, key events, app management, file transfer
• IDE Observer — capture RAD Studio/Delphi/Lazarus IDE screenshots and read compiler errors
• Preview Bridge — live preview of running Pascal apps through Claude's preview system
• FPC Installer — download and install Free Pascal if no compiler is available

Tools

build_dproj details

build_dproj builds an existing real .dproj (multi-unit, with its own search paths, defines, resources, deployment) via MSBuild + rsvars.bat. It does the things ad-hoc shell calls to MSBuild keep getting wrong:

• Reads the dproj's own output paths. Calls MSBuild against a tiny generated helper .proj that imports the dproj and emits DCC_ExeOutput / DCC_DcuOutput / DCC_BplOutput as the dproj's own evaluator sees them. Uses those for deep-clean targeting and artifact lookup — so ..\bin\$(Platform)\$(Config) layouts work the same as the default.
• Auto-resolves the PAServer Connection Profile for iOS / macOS / Linux builds by reading HKCU\Software\Embarcadero\BDS\<ver>\RemoteProfiles. When multiple compatible profiles exist (e.g. a PRODUCTION and STAGING Linux profile) it refuses to silently pick — caller has to pass remote_profile=<name> explicitly. Stops you accidentally deploying to production.
• Chains `/t:Build;Deploy` automatically on Android / iOS / macOS / Linux so the build actually produces an APK or .app, not just an intermediate libProj.so or object file. Pass deploy=False to opt out.
• Detects + optionally synthesizes iOS DeployFile entries that the IDE writes on first deploy. Without these 4 per-Config-Platform entries (ProjectiOSEntitlements, ProjectiOSInfoPList, ProjectiOSLaunchScreen, ProjectOutput) /t:Deploy ships nothing and codesign fails. synthesize_ios_manifest=True writes them after a timestamped .bak backup.
• Deep-cleans the platform's actual output dirs before Rebuild/Clean on staging-based platforms (Android / iOS / macOS / Linux). MSBuild's own Clean leaves PAClient / PAServer staging in place, which is the root cause of "I changed the code but the APK didn't update" reports. Filters paths outside the project tree as a safety guard — never wipes the shared system BPL dir.

Working command-line recipe (matches what build_dproj does for you)

rsvars.bat
MSBuild <Proj>.dproj /t:Build  /p:Config=<Cfg> /p:Platform=<Plat>
MSBuild <Proj>.dproj /t:Deploy /p:Config=<Cfg> /p:Platform=<Plat> /p:Profile=<ConnectionProfile>

build_dproj collapses this into a single call: build_dproj(dproj_path, platform=<Plat>, config=<Cfg>).

Pre-flight check list

If a build fails, walk through these before assuming the MCP is broken:

• For iOS: did you ever IDE-deploy this project to this Config × Platform? If not, run check_ios_deploy(dproj_path, config, platform) and set synthesize_ios_manifest=True on the build.
• For iOSSimARM64: is the iPhoneSimulator SDK imported in Tools → Manage Platforms? (Importing the iPhoneOS device SDK doesn't satisfy the simulator link — ld: file not found: /usr/lib/libiconv.dylib.)
• For any PAServer platform: list_remote_profiles() shows what's registered; sidecar .profile files must exist at %APPDATA%\Embarcadero\BDS\<ver>\<name>.profile for /t:Deploy to read them.
• For Android: is adb on PATH? Is the device authorized (adb_devices)?

PAServer & PAClient

Cross-platform Embarcadero builds (iOS, macOS, Linux) compile through PAServer on a remote Mac or Linux host, driven by paclient.exe on Windows. This MCP wraps both ends:

• build_dproj for iOS/macOS/Linux auto-resolves a Connection Profile, chains /t:Deploy, and synthesizes the iOS manifest if needed (see §build_dproj details).
• paserver_* tools cover the direct file/transfer/diagnostic surface that MSBuild doesn't reach.
• ios_* tools wrap the iOS-bundle pipeline (codesign → IPA → device install) for cases where you want surgical control instead of a full Deploy.

Connection Profiles

PAServer profiles live in HKCU\Software\Embarcadero\BDS\<ver>\RemoteProfiles\ (registry) with a sidecar at %APPDATA%\Embarcadero\BDS\<ver>\<name>.profile. Configure them via RAD Studio → Tools → Options → Environment Options → Connection Profile Manager.

# What's registered:
list_remote_profiles()
# Verify a specific one's reachable:
paserver_check_connection("MACBOOK", timeout=3.0)

Restricted mode

By default PAServer rejects any file op outside its per-profile scratch dir:

/Users/<remote_user>/PAServer/scratch-dir/<windows_user>-<PROFILE>/

Targeting /tmp or /Users/anything-else returns Error: E0006 ... PAServer is running in restricted mode. Either point your transfer at the scratch dir (paserver_scratch_dir composes the path) or have the host operator start PAServer with -restricted=false.

iOS Simulator via SSH

xcrun simctl runs on the Mac and PAClient doesn't expose arbitrary command execution, so simulator control goes through SSH. One-time setup on the Windows side:

# Enable Remote Login on the Mac: System Settings → General → Sharing → Remote Login.
# Then install your public key (asks for the Mac password once):
ssh-copy-id <mac_user>@<mac_host>

Once that's done, the sim_* tools have parity with adb_* — same verbs, same return shape:

mac_ssh_check("192.168.88.79", "andrevanzuydam")   # pre-flight
sim_list(host, user, booted_only=True)              # what's running?
sim_boot(host, user, "<UDID>")
sim_install(host, user, "/Users/.../scratch-dir/...-MACBOOK/MyApp.app")
sim_launch(host, user, "com.embarcadero.MyApp")
sim_screenshot(host, user)                          # returns an Image

Full iOS deploy recipe

# 1. Build the iOS app — Deploy chain leaves a .app in the scratch dir
build_dproj(
    r"D:\src\App.dproj",
    config="Release",
    platform="iOSDevice64",
    synthesize_ios_manifest=True,  # if this is the first iOS deploy
)

# 2. Codesign it (or skip with "-" for ad-hoc dev signing)
ios_codesign(
    "MACBOOK",
    "/Users/macuser/PAServer/scratch-dir/winuser-MACBOOK/App.app",
    "iPhone Developer: Jane Doe (ABCDE12345)",
    entitlement="/Users/macuser/Provisioning/App.entitlements",
)

# 3. Package as IPA
ios_create_ipa(
    "MACBOOK",
    app_path="/Users/.../App.app",
    out_path="/Users/.../App.ipa",
    certificate="iPhone Developer: ...",
    provisioning_profile="/Users/.../App.mobileprovision",
    ipa_type=1,  # ad-hoc; 2 for App Store
)

# 4. Install on attached device (find UDID via xcrun devicectl)
ios_install_ipa("MACBOOK", "/Users/.../App.ipa", "00008101-001234567890123A")

Preview Bridge

The preview bridge lets Claude see and interact with running Pascal desktop applications through its web-based preview system. It serves live screenshots of desktop app windows as a web page.

How it works

Claude Preview Tools (preview_start, preview_screenshot, preview_click)
        | HTTP
        v
Preview Bridge Server (Python/Starlette)
   /               -> HTML page with live screenshot viewer
   /api/screenshot  -> PNG of target window
   /api/controls    -> enumerate child controls with positions
   /api/click       -> click at coordinates or by control hwnd
   /api/type        -> send keystrokes to target window
   /api/move        -> move window to screen position
   /api/resize      -> resize window
        | Win32 PrintWindow API
        v
Running Pascal Desktop Application

API Endpoints

Click Methods

The click endpoint supports three modes, from most to least reliable:

1. Direct control click ({"hwnd": "12345"}) — sends BM_CLICK directly to a control handle. Works regardless of DPI, monitors, or foreground state. Get hwnds from /api/controls.
2. Client-area coordinates ({"x": 200, "y": 142, "client": true}) — uses Win32 ClientToScreen for proper DPI handling.
3. Window-relative coordinates ({"x": 312, "y": 261}) — raw coordinates in the screenshot image space.

Windows App Interaction

The app_click, app_type, and app_key tools let Claude interact with running Windows desktop applications.

Workflow

1. Take a screenshot with screenshot_app to see the current UI
2. Identify pixel coordinates of the target element (button, text field, etc.)
3. Use app_click with those coordinates to click
4. Use app_type to enter text into a focused field
5. Use app_key to send keyboard shortcuts (enter, ctrl+a, alt+f4, etc.)

Clicks use PostMessage with automatic child window targeting, so they reach the correct control. Typing and key events use SendInput for full Unicode and modifier support.

Android Device Interaction (ADB)

Full Android device interaction via ADB. All tools accept an optional device serial number — auto-selects when only one device is connected.

Device Management

• adb_devices — list connected devices with model, Android version, screen size
• adb_device_info — detailed info for a specific device

Screenshots and UI Automation

• adb_screenshot — capture the device screen
• adb_tap / adb_swipe — touch interaction at pixel coordinates
• adb_type_text — type text (auto-escapes for adb shell)
• adb_key — send key events with aliases: home, back, enter, menu, power, volume_up, volume_down, tab, delete, space, escape, app_switch

App Management

• adb_install — install APK files
• adb_list_packages — list installed packages (with optional filter)
• adb_launch_app — launch an app by package name
• adb_stop_app — force-stop an app

File Transfer

• adb_push — push files from PC to device
• adb_pull — pull files from device to PC

Project Templates

The compile_delphi_project tool generates proper Delphi project structure automatically. You specify components and events, and it creates the correct DPR, PAS, and DFM files.

Templates automatically handle:

• Modern Delphi (RAD Studio): namespaced units (Vcl.Forms, System.SysUtils)
• Legacy Delphi (Delphi 7): non-namespaced units (Forms, SysUtils)
• Form definitions (DFM) with proper component declarations
• Event handler wiring between DFM and PAS files

Example

compile_delphi_project(
  project_name="HelloWorld",
  form_caption="My App",
  components='[{"type": "TButton", "name": "btnHello", "caption": "Click Me",
                "left": 100, "top": 100, "width": 120, "height": 35,
                "event": "btnHelloClick"}]',
  events='[{"name": "btnHelloClick", "body": "ShowMessage(\'Hello!\');"}]',
  compiler="C:\\Path\\To\\dcc64.exe"
)

This generates:

• HelloWorld.dpr — project file with proper uses clause
• uMain.pas — unit with form class, component declarations, event handlers
• uMain.dfm — form definition with component properties

Installation

Prerequisites

• Python 3.11+
• uv package manager
• A Pascal compiler (Free Pascal, Delphi, or RAD Studio)

Option 1 — Run from PyPI (recommended)

Once a release is published to PyPI, no clone is needed:

uvx --from claude-pascal-mcp pascal-mcp

Option 2 — Run straight from GitHub (no PyPI required)

uvx --from git+https://github.com/tina4stack/claude-pascal-mcp pascal-mcp

Pin to a tag for reproducibility: git+https://github.com/tina4stack/[email protected].

Option 3 — Local development clone

git clone https://github.com/tina4stack/claude-pascal-mcp.git
cd claude-pascal-mcp

# Install dependencies
uv sync

# Run the MCP server (stdio mode)
uv run pascal-mcp

# Run the preview bridge (HTTP mode)
uv run pascal-preview

Register with Claude Code

PyPI install:

claude mcp add --transport stdio pascal-dev -- uvx --from claude-pascal-mcp pascal-mcp

Git install:

claude mcp add --transport stdio pascal-dev -- uvx --from git+https://github.com/tina4stack/claude-pascal-mcp pascal-mcp

Local clone:

claude mcp add --transport stdio pascal-dev -- uv run --directory /path/to/claude-pascal-mcp pascal-mcp

Or add to your project's .mcp.json — pick the form that matches how you installed:

{
  "mcpServers": {
    "pascal-dev": {
      "command": "uvx",
      "args": ["--from", "claude-pascal-mcp", "pascal-mcp"]
    }
  }
}

{
  "mcpServers": {
    "pascal-dev": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tina4stack/claude-pascal-mcp", "pascal-mcp"]
    }
  }
}

{
  "mcpServers": {
    "pascal-dev": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/claude-pascal-mcp", "pascal-mcp"]
    }
  }
}

Register with Claude Desktop

Add to your claude_desktop_config.json (pick the form matching your install):

{
  "mcpServers": {
    "pascal-dev": {
      "command": "uvx",
      "args": ["--from", "claude-pascal-mcp", "pascal-mcp"]
    }
  }
}

{
  "mcpServers": {
    "pascal-dev": {
      "command": "uv",
      "args": ["run", "--directory", "C:/path/to/claude-pascal-mcp", "pascal-mcp"]
    }
  }
}

Releasing

Maintainer notes — cutting a new release publishes to PyPI automatically.

1. Bump version in pyproject.toml.
2. Commit and tag: git tag v0.1.0 && git push origin v0.1.0.
3. GitHub Actions (.github/workflows/publish.yml) builds the sdist + wheel, publishes to PyPI via Trusted Publishing, and attaches the artifacts to a GitHub Release.

One-time PyPI Trusted Publisher setup (required before the first release):

• Create the project on pypi.org (or reserve it via a first manual uv publish).
• Under Project → Publishing → Add a new publisher, configure GitHub Actions:
• Owner: tina4stack
• Repository: claude-pascal-mcp
• Workflow: publish.yml
• Environment: pypi
• In the GitHub repo, create an environment named pypi (Settings → Environments).

No API tokens needed — OIDC handles auth.

Preview Bridge Setup

Add to .claude/launch.json in your project root:

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "pascal-preview",
      "runtimeExecutable": "/path/to/claude-pascal-mcp/.venv/Scripts/pythonw.exe",
      "runtimeArgs": ["-m", "pascal_mcp.preview_bridge"],
      "port": 18080,
      "autoPort": true
    }
  ]
}

Then in Claude Code, use preview_start("pascal-preview") to open the preview panel.

Supported Compilers

The server automatically detects compilers in this priority order:

1. Free Pascal (fpc) — open source, cross-platform
2. Delphi 64-bit (dcc64) — RAD Studio command-line compiler
3. Delphi 32-bit (dcc32) — RAD Studio / Delphi 7 command-line compiler

You can also specify a full path to any compiler executable:

compile_pascal(source, compiler="C:\\Program Files (x86)\\Embarcadero\\Studio\\37.0\\bin\\dcc64.exe")

Detection checks the system PATH first, then known installation directories:

• C:\FPC\*\bin\*\fpc.exe
• C:\Lazarus\fpc\*\bin\*\fpc.exe
• C:\Program Files (x86)\Embarcadero\Studio\*\bin\dcc*.exe

License

MIT