Native macOS client for Google Cloud IAP.

IAP Desktop alternative for macOS. Connect to GCP VMs over RDP via IAP without Windows.

Google provides IAP Desktop only for Windows. macOS users are forced to use CLI (gcloud iap tunnel) or Windows VM.

Access Windows VMs from anywhere

IAP Tunnel Manager uses Identity-Aware Proxy (IAP) to connect to VM instances so that you can:

• Connect to VM instances that don't have a public IP address
• Connect from anywhere over the internet
• Apply zero-trust security to your VMs

The application automatically manages IAP TCP tunnels for you, finding free local ports and handling the connection lifecycle.

Connect to Windows VMs with Remote Desktop

IAP Tunnel Manager makes it easy to establish RDP connections:

• Auto Port Selection - Automatically finds free local ports for tunnels
• Copy RDP Address - Quick copy of localhost:<port> for any RDP client
• Real-time Logs - View tunnel connection status and diagnostics
• One-Click FreeRDP Connection - Connect instantly with FreeRDP using credentials from Keychain
• Open Windows App - Launch Microsoft Windows App directly with one click

Manage VMs across projects

IAP Tunnel Manager gives you a consolidated view of your VMs:

• Live Search - Filter projects and VMs as you type
• Tunnel Management - Start, stop, and monitor tunnel status
• Save Connections - Save frequently used connections for quick access
• Multi-project Support - Browse VMs across all your Google Cloud projects

Windows App Integration

If you have Microsoft Windows App installed, IAP Tunnel Manager can automatically create RDP bookmarks with credentials.

Create a bookmark

Click the "..." menu and select "Create Windows App Bookmark":

Configure bookmark options

Choose to generate a new Windows password and store it securely in macOS Keychain:

Credentials saved

The password is generated, saved to Keychain, and the bookmark is created in Windows App:

Ready to connect

Your bookmark appears in Windows App, ready to use:

FreeRDP One-Click Connection

IAP Tunnel Manager includes built-in support for FreeRDP, allowing you to connect to Windows VMs with a single click. FreeRDP is an open-source Remote Desktop Protocol client that provides excellent performance and features on macOS.

Quick Connect with FreeRDP

Once you have a saved connection with credentials stored in macOS Keychain:

1. Start the tunnel - Click "Start Tunnel" to establish the IAP connection
2. Click "Connect with FreeRDP" - The app automatically launches FreeRDP with:
   • Pre-configured connection settings
   • Credentials retrieved from macOS Keychain
   • Optimized display settings (dynamic resolution, graphics acceleration)
   • Clipboard and sound support enabled

Installing FreeRDP

If FreeRDP is not installed, install it using Homebrew:

brew install freerdp

The app automatically detects FreeRDP installation in common locations (/opt/homebrew/bin/sdl-freerdp, /usr/local/bin/sdl-freerdp, or /usr/bin/sdl-freerdp).

FreeRDP Features

When connecting via FreeRDP, you get:

• Dynamic Resolution - Automatically adjusts to your display
• Graphics Acceleration - Hardware-accelerated rendering for smooth performance
• Clipboard Integration - Copy and paste between macOS and Windows
• Audio Support - Redirect audio from Windows VM to your Mac
• Secure Credential Storage - Passwords stored securely in macOS Keychain

Use with Claude (MCP)

The same Go binary set ships iap-mcp, a Model Context Protocol server that exposes every IAP Tunnel Manager capability as MCP tools and resources. Wire it into Claude Desktop, Claude Code, or Cursor and ask in plain English: "open RDP into prod-bastion-01", "rotate the Administrator password and update the bookmark", "why is my tunnel stuck?".

What you get

• 32 MCP tools covering ADC auth, project/VM listing, saved connections, tunnels, SSH key install (Linux), Windows password rotation, Keychain, Windows App bookmarks, and FreeRDP launch.
• 3 MCP resources for live state: iap://connections, iap://tunnels, and per-tunnel logs at iap://tunnels/{id}/logs.
• Shared ~/Library/Application Support/IAP Tunnel Manager/config.json with the desktop app — favorites you create from Claude show up in the UI and vice versa.
• Tools are annotated with read-only / destructive hints so MCP-aware clients can require explicit approval for mutating actions (windows_reset_password, connections_remove, auth_revoke, …).

Build and install the MCP server

go build -o /usr/local/bin/iap-mcp ./cmd/iap-mcp

(Requires the same gcloud auth application-default login already used by the desktop app.)

Wire into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "iap-tunnel-manager": {
      "command": "/usr/local/bin/iap-mcp"
    }
  }
}

Restart Claude Desktop. The tools appear under the plug icon.

Wire into Cursor

Edit ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{
  "mcpServers": {
    "iap-tunnel-manager": {
      "command": "/usr/local/bin/iap-mcp"
    }
  }
}

Install the Skills bundle

Skills (skills/*/SKILL.md) teach Claude when and how to use the tools. They're loaded only when the user's intent matches a skill's description, so they're cheap.

mkdir -p ~/.claude/skills
cp -r skills/* ~/.claude/skills/

Bundled skills:

Skill	Use when
connect-windows-vm	User wants to RDP into a Windows GCE VM
connect-linux-vm	User wants an SSH session to a Linux GCE VM
rotate-windows-credentials	User explicitly asks to rotate a Windows password
debug-tunnel	User reports a broken / hanging tunnel
onboard-new-vm	User wants to add new GCE VMs as saved connections

For Cursor, copy the same files into .cursor/skills/ (or ~/.cursor/skills/).

Try it

You:    What VMs do I have in my dev project?
Claude: [calls projects_list, then vms_list]
        Found 7 VMs in `acme-dev`. 4 are running, 2 are Windows.
        Want me to start a tunnel to one?

You:    Open Windows App for prod-bastion-01.
Claude: [calls connections_list → tunnels_start_for_connection → freerdp_launch]
        Tunnel up on localhost:53301; FreeRDP launching now.

---

Get started

Installation

Download the latest release from the Releases page.

The application is code-signed with an Apple Developer ID certificate and notarized by Apple, ensuring secure installation and execution on macOS. Simply download, open, and start using the app - no manual security approval required.

Configure IAP in your project

1. Install Google Cloud CLI

Install the Google Cloud CLI for your platform. This is required for authentication.

2. Authenticate with Google Cloud

This app uses Application Default Credentials (ADC). Authenticate with:

gcloud auth application-default login

3. Required IAM Permissions

Your Google account needs the following permissions:

Role	Purpose
roles/viewer	List projects
roles/compute.viewer	List VM instances
roles/iap.tunnelResourceAccessor	Create IAP tunnels

4. Configure Firewall Rules

Ensure your VPC has a firewall rule allowing IAP traffic:

Setting	Value
Source IP range	35.235.240.0/20
Target	VMs you want to connect to
Ports	3389 (RDP)

Connect to a Windows VM

1. Launch the app - It will check for valid GCP credentials
2. Click "+ New" - Create a new connection
3. Select a project - Use the search box to filter projects
4. Select a VM - Choose the VM you want to connect to
5. Save Connection - Click "Save Connection" to save for quick access
6. Start Tunnel - Click "Start Tunnel" to create the IAP connection
7. Connect via RDP - Choose your preferred connection method:
   • Connect with FreeRDP - One-click connection using FreeRDP (requires FreeRDP installed)
   • Open Windows App - Launch Microsoft Windows App directly
   • Copy Address - Copy localhost:<port> for use with any RDP client

Troubleshooting

"Application Default Credentials not found"

Run gcloud auth application-default login and restart the app.

"Permission denied" when listing projects

Ensure your account has the roles/viewer role at the organization or folder level.

"Failed to dial IAP"

Check that:

• The VM is running
• You have roles/iap.tunnelResourceAccessor permission
• The firewall allows IAP traffic (35.235.240.0/20)

Tunnel starts but RDP fails

• Verify the VM has RDP enabled (Windows) or xrdp installed (Linux)
• Check that port 3389 is listening on the VM

FreeRDP connection fails

If FreeRDP fails to launch:

• FreeRDP not found: Install FreeRDP using brew install freerdp
• Credentials missing: Ensure you've saved the connection with credentials stored in Keychain
• Tunnel not running: Make sure the tunnel is started before connecting with FreeRDP
• Check logs: View the tunnel logs in the app for detailed error messages from FreeRDP

FAQ

Is there an official Google IAP Desktop for macOS?

No. Google provides IAP Desktop only for Windows. macOS users must use CLI or third-party tools.

How can I use Google Cloud IAP on macOS?

You can use gcloud iap tunnel (CLI) or a native macOS client like go-iap-mac.

Is this an IAP Desktop alternative for Mac?

Yes. This project provides a native macOS UI for managing IAP SSH/RDP connections.

Does this replace gcloud?

No. It uses gcloud under the hood and simplifies daily usage.

---

Development

Requirements

• Go 1.21+
• Node.js 18+
• Wails CLI v2

Install Wails CLI

go install github.com/wailsapp/wails/v2/cmd/wails@latest

Run in Development Mode

wails dev

This starts the app with hot-reload for frontend changes.

Build the Application

# Install frontend dependencies
cd frontend && npm install && cd ..

# Download Go dependencies
go mod tidy

# Build for macOS
wails build -platform darwin/universal

The built application will be in build/bin/.

Build the MCP server

go build -o /usr/local/bin/iap-mcp ./cmd/iap-mcp
iap-mcp --help

To run it for debugging:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | iap-mcp

Project Structure

go-iap/
├── main.go               # Wails entry (embed frontend, Run, Bind)
├── cmd/iap-mcp/          # MCP stdio server binary (Claude integration)
├── internal/ui/          # Wails-bound App and orchestration (split .go files)
├── internal/mcpserver/   # MCP tool + resource registrations backed by ui.App
├── internal/             # appconfig, gcp, gcessh, iaptunnel, session, winapp, mackeychain
├── skills/               # Claude/Cursor SKILL.md bundles for end-user workflows
├── wails.json            # Wails configuration
├── go.mod                # Go dependencies
├── frontend/
│   ├── index.html        # Main HTML
│   ├── package.json      # Frontend dependencies
│   ├── vite.config.js    # Vite configuration
│   └── src/
│       ├── main.js       # Frontend JavaScript
│       └── style.css     # Styles
├── CLOUD.md              # Per-package map for AI agents (read first)
└── README.md

Technical Details

IAP Tunnel Implementation

This app uses the cedws/iapc library which implements the Google IAP SSH Relay v4 protocol. The tunnel:

1. Listens on a local port (127.0.0.1)
2. For each incoming connection, establishes an IAP WebSocket tunnel
3. Proxies data bidirectionally between local and remote endpoints

API Usage

API	Purpose
Resource Manager API	List accessible GCP projects
Compute Engine API	List VM instances (aggregated across all zones)
IAP TCP Forwarding	WebSocket-based tunnel protocol

License

MIT License