Skip to content
← Back to Tutorials

How to Set Up PigeonCast MCP on Mac

Beginner10 minJuly 3, 2026

This guide shows how to install PigeonCast Tools on a Mac, connect PigeonCast to AI assistants such as Cursor, Claude Desktop, Codex, and Windsurf, and use natural-language prompts to control the PigeonCast app.

Topics covered:

PigeonCast MCPMacCodexCursorClaude DesktopWindsurf

Step-by-Step Guide

1

Install PigeonCast Tools on Your Mac

PigeonCast Tools works on macOS 13 or later on both Apple Silicon and Intel Macs.

Before you start, make sure the main PigeonCast app is installed and can be opened from your Applications folder. The AI assistant can help only when PigeonCast is running.

Step 1: Open the downloaded PigeonCast Tools installer image (.dmg).

Step 2: Double-click Install or Install.command.

Step 3: If your Mac asks for a password, enter your login password and confirm.

Step 4: Wait until you see the installation complete message.

2

Connect PigeonCast in Your AI Assistant

After installation, add the PigeonCast connection to the AI app you use most often. You only need to complete this setup once.

The installer includes a config folder with sample configurations for different apps. Replace the sample path with the actual local path of pigeoncast-mcp on your Mac, then fully quit and reopen the AI app after saving the config.

Cursor

Step 1: Open Cursor and go to Settings -> MCP.

Step 2: Add a new MCP server.

Step 3: Paste in the content from the Cursor sample in the config folder.

Step 4: Save the settings, fully quit Cursor, and open it again.

Step 5: Confirm that pigeoncast appears as connected in the MCP list.

Claude Desktop

Step 1: Fully quit Claude from the menu bar.

Step 2: Open the Claude MCP configuration file with TextEdit. A sample is included in config/claude-desktop.

Step 3: Add the PigeonCast config based on the sample and save the file.

Step 4: Reopen Claude Desktop.

Windsurf

Step 1: Open the MCP-related settings in Windsurf.

Step 2: Add PigeonCast by following the Windsurf sample in the config folder.

Step 3: Restart Windsurf.

Codex (OpenAI Codex)

Step 1: Open Codex and go to Settings -> MCP.

Step 2: Add an MCP server named pigeoncast.

Step 3: Set the program path to /usr/local/bin/pigeoncast-mcp. If you installed with Install, this is usually the correct path.

Step 4: Save the settings, fully quit Codex, and open it again.

Step 5: Confirm that pigeoncast is enabled in MCP settings.

If you use the Codex command line, run:

codex mcp add pigeoncast -- /usr/local/bin/pigeoncast-mcp
codex mcp list

Other AI apps

Use the matching samples in the installer config folder and add them in the MCP, Tools, or Plugins settings of your app.

3

Use Ready-to-Copy PigeonCast Prompts

After the connection succeeds, make sure PigeonCast is open, then try prompts like the examples below.

Check whether PigeonCast is running

Please check whether PigeonCast is running.

Search for TVs or casting devices on your network

Use PigeonCast to search for devices on my local network that can receive a cast, and list them for me.

Cast your computer screen to a TV

Use PigeonCast to search for available receiving devices, pick one, and cast my computer screen to it. If I need to enter the PIN or password shown on the TV, let me know.

Cast only one app window

Use PigeonCast to search for devices, then cast the Safari window to the living room TV.

Replace Safari with the name of the app you actually want to cast.

Stop the current casting session

Use PigeonCast to stop the current screen mirroring session.

Open the PigeonCast interface

Open the Send Screen page in PigeonCast for me.

Open the main PigeonCast window for me.

Run a combined action

First search for casting devices in my home, choose a PigeonCast TV, and start casting my main screen to it. If a PIN appears on the TV, remind me to enter it.

4

Fix Permissions and Connection Issues

Step 1: If mirroring fails immediately, open System Settings -> Privacy & Security -> Screen Recording and enable screen recording permission for PigeonCast.

Step 2: Always open PigeonCast before sending prompts to the AI assistant.

Step 3: If the TV asks for an AirPlay PIN or password, tell the AI assistant the PIN or enter it manually in the PigeonCast window.

Step 4: Adjust mirroring parameters such as resolution, fps, and quality directly in the AI chat when needed.

Step 5: If the AI assistant cannot connect to PigeonCast, confirm that PigeonCast is open, fully quit and reopen the AI app, then try again.

Note: PigeonCast Tools lets you control the installed PigeonCast app through an AI conversation. It does not replace installing the main PigeonCast application.

5

Get Help

If you still need help, use the support channels below.