@zibby/mcp-cli

Zibby's local-essential CLI as a Model Context Protocol server. Lets any MCP-aware AI agent — Claude Code, Cursor, OpenAI Codex, Gemini CLI, Continue, Cline, Aider, Goose — log in to Zibby, scaffold/validate/run workflows on local disk, and deploy or download workflows from a chat session.

Looking for list_projects, trigger_workflow, workflow_logs, marketplace apps, ticket/integration browsing, etc.? Those tools moved to the Zibby Remote MCP at https://api-prod.zibby.app/mcp (HTTP transport, 71 tools, no install). Hook your agent up to both — this stdio package for the things that touch your filesystem, the remote MCP for everything else. The remote MCP picks up server-side changes without you having to re-publish or upgrade npm.

What you get

9 MCP tools, every one of them genuinely local:

| Tool | Why it has to be local | |---|---| | zibby_login | Opens the user's browser (device-code OAuth) and writes the session token + cached project API tokens to ~/.zibby/config.json. | | zibby_logout | Clears the saved session from ~/.zibby/config.json. | | zibby_status | Reads ~/.zibby/config.json to show which login is active on this machine. (The remote MCP also has a zibby_status, but only this one sees the local file.) | | zibby_list_templates | Lists workflow templates bundled with the local @zibby/cli — no network. | | zibby_scaffold_workflow | Writes .zibby/workflows/<name>/ files to local disk. | | zibby_validate_workflow | Reads local workflow files + runs the validator (~30ms, no API). | | zibby_run_workflow_local | Spawns a local node process to run a workflow against local data. | | zibby_deploy_workflow | Bundles the local workflow folder + dependencies, then uploads. Bundling is local. | | zibby_download_workflow | Downloads a deployed workflow back to local disk. Requires explicit user confirmation. |

Destructive ops (workflow delete, env set/unset, schedule set/clear, creds) are intentionally not exposed. Manage those from the zibby CLI directly, or via the Zibby Remote MCP where they exist.

Prerequisites

• Node.js ≥ 18 on the user's machine
• A Zibby account (sign up at zibby.dev)

That's it. No global npm install needed — npx handles the bundle (which includes @zibby/cli).

Install (per agent)

Claude Code

~/.claude/settings.json (or ~/.claude.json on older versions):

{
  "mcpServers": {
    "zibby": {
      "command": "npx",
      "args": ["-y", "@zibby/mcp-cli"]
    },
    "zibby-remote": {
      "type": "http",
      "url": "https://api-prod.zibby.app/mcp"
    }
  }
}

Then in Claude Code: "log in to Zibby" → it'll call zibby_login and open the browser.

Cursor

~/.cursor/mcp.json:

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

OpenAI Codex CLI

~/.codex/config.toml:

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

Gemini CLI

~/.gemini/settings.json:

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

Claude Desktop (macOS)

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

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

Windows note

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

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

Authentication

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 by zibby_login and cached locally in ~/.zibby/config.json. The MCP server picks the right token automatically when you call a project-scoped tool like zibby_deploy_workflow or zibby_download_workflow.

If you grant your account access to a new project, re-run zibby_login (or zibby_logout + zibby_login) to refresh the cached project list.

All credentials live in ~/.zibby/config.json (mode 0600). The MCP server reads/writes that file directly — no separate credential store.

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.

How a typical agent chat flow looks

User:  Deploy the browser-test template to my "playhouse" project.
Agent: → (via Remote MCP) zibby_list_projects   (finds projectId)
       → zibby_scaffold_workflow                (browser-test-automation → .zibby/workflows/playhouse-tests/)
       → zibby_validate_workflow                (catches obvious errors locally)
       → zibby_deploy_workflow                  (bundles local folder, uploads, returns UUID + version)
       → "Deployed v1 of playhouse-tests. UUID 988…"

User:  Run it against staging.zibby.dev.
Agent: → (via Remote MCP) zibby_trigger_workflow    (input: { url: "https://staging.zibby.dev" })
       → returns { jobId: "abc-123" }
       → (via Remote MCP) zibby_get_workflow_job_logs   (jobId: "abc-123")
       → "Run completed. Found 0 errors."

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. Re-run zibby_login (or zibby_logout + zibby_login) to refresh. | | Tool returns text with ANSI color codes | Some agent UIs don't strip them. We set NO_COLOR=1 already; if you still see them, your agent's display is the issue. | | npx -y hangs on first install | First-time download. Subsequent invocations are cached. | | Tool times out on long deploys | The wrapped CLI command exceeded 10 min. Re-run from a terminal with zibby workflow deploy to see live output. | | Wanting list_projects / trigger_workflow / workflow_logs | Those live in the Zibby Remote MCP. Add it as a second mcpServers entry (https://api-prod.zibby.app/mcp). |

Security model

• No shell interpolation — all CLI invocations use execFile with argv arrays
• Minimum env passthrough — only HOME, USER, PATH, and the project-scoped ZIBBY_API_KEY are forwarded to the child CLI process
• Destructive ops excluded — see "What you get" above
• zibby_download_workflow requires confirm: true — agent must explicitly opt in after confirming dest path with the user
• API tokens never returned to the agent — they live in ~/.zibby/config.json only

Versioning

@zibby/mcp-cli pins a specific @zibby/cli version in its dependencies. Upgrading the MCP package upgrades the bundled CLI in lockstep. To check which CLI version is bundled:

npx -y @zibby/mcp-cli --version          # MCP server version
node -p "require('@zibby/cli/package.json').version"   # bundled CLI version (after first npx run)

License

Proprietary — Copyright (c) 2026 Zibby Labs. All rights reserved. Unauthorized copying, distribution, or use is prohibited.