---
sidebar_position: 7
title: "@zibby/mcp-cli"
---

# @zibby/mcp-cli

A Model Context Protocol (MCP) server that exposes the Zibby CLI surface — deploy, run, debug, trigger — to any MCP-aware AI agent. Install once, drive Zibby from Claude Code / Cursor / OpenAI Codex / Gemini CLI / Continue / Cline / Aider / Goose without leaving chat.

```bash
# Not installed manually — the agent's `npx` invocation handles it.
# See "Install" below for per-agent config.
```

## What it exposes

13 MCP tools, all wrapping the underlying `@zibby/cli`:

| Tool | What it does |
|---|---|
| `zibby_login` | Opens the user's browser for device-code OAuth. Saves session to `~/.zibby/config.json`. |
| `zibby_logout` | Clears the saved session. |
| `zibby_status` | Who is logged in, how many projects are cached, whether the session is still valid. |
| `zibby_list_projects` | List the Zibby projects the user has access to. |
| `zibby_list_templates` | List official agent templates (browser-test-automation, code-analysis, generate-test-cases, …). |
| `zibby_scaffold_agent` | Scaffold `.zibby/workflows/<name>/` from an official template. |
| `zibby_validate_agent` | Static-check a local agent (~30 ms, no API call). |
| `zibby_list_agents` | List agents: local, remote, or both. |
| `zibby_deploy_agent` | Deploy a local agent to a project. |
| `zibby_trigger_agent` | Trigger a deployed agent by UUID. Returns `jobId`. |
| `zibby_agent_logs` | Fetch the latest N log lines from a run (one-shot — call again for newer lines). |
| `zibby_run_agent_local` | Run an agent on the user's machine one-shot, for debugging. No cloud. |
| `zibby_download_agent` | Pull a deployed agent back to local. Requires explicit `confirm: true` from the agent. |

**Destructive operations are intentionally not exposed.** Agent deletion, env-var mutation, schedule changes, and credential management stay in the `zibby` CLI directly. The agent has to involve the user out-of-band for those.

## Install

`@zibby/mcp-cli` ships as a stdio MCP server. The agent's host process spawns it via `npx -y` — no global install needed. The user just needs **Node.js ≥ 18** on their machine.

### Claude Code

`~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### OpenAI Codex CLI

`~/.codex/config.toml`:

```toml
[mcp_servers.zibby]
command = "npx"
args = ["-y", "@zibby/mcp-cli"]
```

### Gemini CLI

`~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### Claude Desktop (macOS)

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

```json
{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    }
  }
}
```

### Windows

If your agent on Windows can't find `npx`, wrap with `cmd /c`:

```json
{
  "mcpServers": {
    "zibby": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@zibby/mcp-cli"]
    }
  }
}
```

## A typical agent chat

```
User:  Deploy the browser-test template to my "playhouse" project.
Agent: → zibby_list_projects
       → zibby_scaffold_agent (browser-test-automation → .zibby/workflows/playhouse-tests/)
       → zibby_validate_agent
       → zibby_deploy_agent
       → "Deployed v1 of playhouse-tests. UUID 988…"

User:  Run it against staging.zibby.dev.
Agent: → zibby_trigger_agent (input: { url: "https://staging.zibby.dev" })
       → zibby_agent_logs (lines: 200, jobId: "abc-123")
       → "Run completed. Found 0 errors."
```

## Auth model

Two-stage by design (mirrors how the `zibby` CLI works):

1. **Session token** (`zibby_login`) — device-code OAuth via browser. Identifies the user.
2. **Per-project API tokens** — fetched at login time and cached locally. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_agent`.

All credentials live in `~/.zibby/config.json` (mode `0600`). The same file `zibby login` writes — so if you've already done `zibby login` from a terminal, the MCP server picks up that session.

The user's password never touches the MCP server: login is OAuth in the browser, and only the resulting session token comes back to the local file.

## Security guarantees

- **No shell interpolation** — every CLI invocation uses `execFile` with argv arrays.
- **Minimum env passthrough** — only `HOME`, `USER`, `PATH`, and the project-scoped `ZIBBY_API_KEY` reach the child CLI process.
- **API tokens never returned to the agent** — they live in `~/.zibby/config.json` only, read server-side per call.
- **Destructive ops excluded** — see the table above.
- **`zibby_download_agent` requires `confirm: true`** — the schema rejects calls without it. Agents must explicitly opt in after confirming the destination path with the user.

## Troubleshooting

| Problem | Likely cause |
|---|---|
| `Not logged in` on every call | `~/.zibby/config.json` missing or corrupted. Call `zibby_login`. |
| `No API token cached for project` | Project list out of date. Call `zibby_list_projects` to refresh. |
| `npx -y` hangs on first install | First-time download. Subsequent invocations are cached by npm. |
| Tool times out on long deploys | The wrapped CLI command exceeded 10 min. Re-run from a terminal to see live output. |

## Versioning

`@zibby/mcp-cli` pins a specific `@zibby/cli` version in its `dependencies`. Upgrading the MCP package upgrades the bundled CLI in lockstep. Users get the right CLI automatically — no need to coordinate two installs.

## Source

[github.com/ZibbyHQ/zibby-agent → packages/mcps/cli](https://github.com/ZibbyHQ/zibby-agent/tree/main/packages/mcps/cli)