[](LICENSE)
[](https://www.swift.org)
[](https://github.com/M-Pineapple/warp-command-runner/stargazers)
[](https://glama.ai/mcp/servers/M-Pineapple/warp-command-runner)
**Give any chat AI a real terminal.** You ask in Warp, Claude Desktop, ChatGPT desktop, or any other MCP host. The model types the command into your [Warp](https://app.warp.dev/referral/G9W3EY) tab, captures the output, and tells you what happened. Forty tools: command execution, project setups, file watching, SSH, clipboard, environment intelligence. macOS, Swift, open source.
This is for people who **don't live in Cursor or Claude Code**. If you already chat with Grok, ChatGPT, Claude, or Gemini from a desktop app (especially Warp's agent panel), add this MCP and that chat can read your files and run commands on your machine.
> Built for [Warp Terminal](https://app.warp.dev/referral/G9W3EY). The five most powerful tools route commands **visibly** into your active Warp tab. Register the same binary with as many MCP hosts as you want — the server speaks standard MCP over stdio and does not care which model is calling.
**Can any cloud AI use this?** Any **local MCP host** can, over stdio. Phone apps and websites need **remote MCP**: you run `--http` and publish HTTPS with a tunnel **you** own. Guide: [`docs/REMOTE.md`](docs/REMOTE.md). Matrix: [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md).
## What's new in v8.0.2
Release 8.0.2 builds with swift-sdk 0.12.1 (no local patch) and ships a committed `Package.resolved` so a fresh clone resolves the same versions. Remote `--http` pairing from 8.0.1 still applies: a one-time code shown on the Mac authorizes a new client. Remote-mode users should update and delete `~/.warp-command-runner/oauth-store.json` to re-pair. Details: [`docs/REMOTE.md`](docs/REMOTE.md).
The data folder is `~/.warp-command-runner` unless you set `WCR_HOME` (see [Data directory](#data-directory)).
## Quick start
You need macOS 13 or later, Swift 6.0+ (Xcode 16+), and a local MCP host such as Warp Agent or Claude Desktop.
```bash
git clone --branch v8.0.4 --depth 1 https://github.com/M-Pineapple/warp-command-runner.git
cd warp-command-runner
./build.sh
```
`./build.sh` resolves packages, applies the required swift-sdk patch, builds the release binary, and wraps it in `.build/release/warp-command-runner.app`.
Point your host at the binary inside that bundle. For Warp Agent, merge this into `~/.warp/.mcp.json` and replace the path with yours:
```json
{
"mcpServers": {
"warp-command-runner": {
"command": "/absolute/path/to/warp-command-runner/.build/release/warp-command-runner.app/Contents/MacOS/warp-command-runner",
"args": []
}
}
}
```
Restart the host. Ask it to run `swift --version`. That uses `execute_pipeline` and needs no Accessibility grants.
### Data directory
Config, command history, templates, and SSH profiles live in `~/.warp-command-runner`. Set `WCR_HOME` to use a different folder. The value must be an absolute path or start with `~/`. Relative values are ignored. macOS ignores a process-level `HOME=` for `FileManager.homeDirectoryForCurrentUser`, so `WCR_HOME` is the supported override. The folder is created with owner-only permissions (`0700`). ConfigManager uses the same resolution.
```json
{
"mcpServers": {
"warp-command-runner": {
"command": "/absolute/path/to/warp-command-runner/.build/release/warp-command-runner.app/Contents/MacOS/warp-command-runner",
"args": [],
"env": {
"WCR_HOME": "~/wcr-test"
}
}
}
}
```
When `WCR_HOME` is set to a valid path, the server does not copy `~/.claude-command-runner` into that folder.
An unsigned build is enough for the 34 non-keystroke tools. The five Warp-routing tools need a signed `.app` in `/Applications/`. Host snippets, signing, and the Sequoia recipe are under [Installation](#installation). Phone and website hosts need `--http` plus your own HTTPS tunnel. See [`docs/REMOTE.md`](docs/REMOTE.md).
## What's new in v8.0.0 — remote MCP
Opt-in Streamable HTTP so Grok, ChatGPT, and Claude can call this Mac from a phone or a website. You create the public HTTPS URL (your Cloudflare tunnel, your Tailscale Funnel, or your reverse proxy). This project does not host a relay.
- `warp-command-runner --http` listens on `127.0.0.1` only (default port 8741)
- OAuth 2.1 with PKCE and Dynamic Client Registration
- Warp-routing (keystroke) tools stay off for remote callers; use `execute_pipeline`
- `--remote-doctor` and `--install-agent` for a login LaunchAgent
Local stdio is unchanged. Details: [`docs/REMOTE.md`](docs/REMOTE.md).
## What's new in v7.0.0 — rebrand
Formerly **Claude Command Runner**. Same engine, host-agnostic name:
- Product, binary, bundle ID, and config dir renamed to Warp Command Runner (`warp-command-runner`, `~/.warp-command-runner`)
- Existing `~/.claude-command-runner` data is copied on first launch (the old folder is left in place)
- MCP `serverInfo` name is `Warp Command Runner` so every host lists it that way
- Config snippets for Warp, Claude Desktop, ChatGPT desktop, Cursor, VS Code, and a generic stdio host
- Honest compatibility doc: stdio MCP works everywhere a local host exists. Remote MCP is opt-in in v8 (`docs/REMOTE.md`).
v6.x history (Warp deeplinks, OSC 777, dual-consumer Warp Agent, 40 tools) is unchanged — see [CHANGELOG.md](CHANGELOG.md).
## Overview
Warp Command Runner is an **MCP server**. One binary, any MCP client:
- Execute terminal commands from a conversation
- Chain commands with pipelines and failure modes
- Stream output for long builds
- Save and reuse command templates with variables
- Auto-capture output with intelligent timing
- Track command history
- Read/write the macOS clipboard
- Probe environment context (git, venv, Docker, Node)
- Parse command output into structured JSON
- Manage workspace profiles (optionally as Warp launch configs)
- Open Warp tabs via `warp://` deeplinks and send commands to the active tab
- Watch files and trigger commands on changes
- Execute commands on remote hosts via SSH
- Surface status into Warp as OSC 777 `warp://cli-agent` events
- Optional shell shim: preexec / command-finished events over a Unix socket
## 🧭 Which app should I register this with?
The protocol is MCP. The **value** depends on whether the host is local and whether Warp is your terminal. Details in [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md).
| Host | Config | Recommended? |
|---|---|---|
| **[Warp Agent](https://app.warp.dev/referral/G9W3EY)** (Grok, Claude, GPT, Gemini — whatever Warp is set to) | `~/.warp/.mcp.json` | Yes — best fit. See [docs/WARP_AGENT.md](docs/WARP_AGENT.md) |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | Yes |
| **ChatGPT desktop** (Connectors / Developer Mode) | host MCP settings; snippet in `config/chatgpt-mcp.json` | Yes, if your plan exposes local MCP |
| **VS Code / Continue / Cline / Windsurf** | their MCP settings; see `config/` | Optional |
| **Cursor** | `~/.cursor/mcp.json` | Optional — Cursor already has a terminal |
| **Claude Code** | `~/.claude.json` | Niche — it already has Bash |
| **Browser / phone chats** (chatgpt.com, grok.com, claude.ai) | custom connector URL | Optional — needs v8 `--http` plus **your** HTTPS tunnel. [`docs/REMOTE.md`](docs/REMOTE.md) |
### Quick decision tree
- **You use Warp and chat with Grok / ChatGPT / Claude / Gemini inside Warp?** → Register in `~/.warp/.mcp.json`. That's the whole product.
- **You use Claude Desktop (or ChatGPT desktop) and want commands visible in Warp?** → Register there too. Same binary.
- **You use Cursor or Claude Code and want everything in one pane?** → You probably don't need this.
- **You only use a website or phone chatbot?** → Stdio cannot reach that tab. Enable remote MCP (`docs/REMOTE.md`) or use a desktop MCP host.
Five of the 40 tools (`execute_command`, `execute_with_auto_retrieve`, `execute_with_streaming`, `run_template`, `send_to_session`) are the Warp-routing ones. The rest are ordinary server-side utilities (clipboard, SSH, snapshots, …) that work from any host.
## 🎯 Key Features
### Command Pipelines
Chain multiple commands with intelligent failure handling:
```json
{
"steps": [
{"name": "Build", "command": "swift build", "on_fail": "stop"},
{"name": "Test", "command": "swift test", "on_fail": "continue"},
{"name": "Package", "command": "swift build -c release", "on_fail": "stop"}
]
}
```
**Failure modes:**
- `stop` – Halt pipeline on failure
- `continue` – Log error and proceed to next step
- `warn` – Show warning and continue
### Output Streaming
Real-time output for long-running commands:
```json
{
"command": "swift build -c release",
"update_interval": 3,
"max_duration": 180
}
```
Perfect for:
- Long compilation processes
- Test suites
- Any command that previously "hung" waiting for output
### Command Templates
Save reusable patterns with variable substitution:
```json
// Save a template
{
"name": "swift-release",
"template": "cd {{project}} && swift build -c release",
"category": "Swift Development",
"description": "Build Swift project in release mode"
}
// Run with variables
{
"name": "swift-release",
"variables": {"project": "~/GitHub/MyApp"}
}
```
Templates are stored in `~/.warp-command-runner/templates.json` and persist across sessions.
### Smart Auto-Retrieve
The `execute_with_auto_retrieve` command intelligently detects command types and adjusts wait times:
- **Quick commands** (echo, pwd): 2-6 seconds
- **Moderate commands** (git, npm): up to 20 seconds
- **Build commands** (swift build, make): up to 77 seconds
- **Test commands**: up to 40 seconds
## 📊 Why Warp Terminal?
[Warp Terminal](https://app.warp.dev/referral/G9W3EY) is the primary integration target. Other terminals work for the basics — Warp uniquely unlocks deeplinks, OSC 777, the native agent panel, and launch configs:
| Feature | Warp | Terminal.app | iTerm2 |
|---------|------|--------------|---------|
| `warp://` deeplinks for tab/window | ✅ | ❌ | ❌ |
| Native MCP agent panel — chat with Grok, ChatGPT, Claude, Gemini *in* the terminal | ✅ (`~/.warp/.mcp.json`) | ❌ | ❌ |
| OSC 777 cli-agent event channel for status surfacing | ✅ | ❌ | ❌ |
| Workspace profile → recognized launch config | ✅ (`~/.warp/launch_configurations/`) | ❌ | ❌ |
| AppleScript-driven new tab + keystroke send | ✅ | ✅ | ✅ |
| Modern UI/UX | ✅ | ⚠️ | ⚠️ |
Output capture (`/tmp/