imperal-mcp

Python 3.7 – 3.14 · pip install imperal-mcp works on every one of them.

Build, ship, and run real cloud apps on Imperal — straight from your AI agent.

imperal-mcp puts the app-building power of Imperal Cloud — the ICNLI AI Cloud OS that Webbee 🐝 runs on — inside any MCP-capable agent. Connect it to Claude, Claude Code, Codex, Cursor, Gemini CLI, Cline, Windsurf, or Goose, sign in with your own Imperal account, and your agent can design, deploy, and operate real cloud apps for you — data, logic, and UI included — without ever leaving the chat.

You describe what you want. Your agent builds it. Imperal runs it.

What you can do

Tell your agent what you want — and it builds it on Imperal, end to end:

• Design an app from a description — its data/entities, the functions that act on them, and the UI panels that render them, as one clean declarative spec.
• Validate it instantly against the live Imperal schema, before anything ships.
• Smoke-test a function in an isolated sandbox and see it actually work.
• Deploy it live to your Imperal account — instantly available, fleet-wide.
• List & inspect every app you've built.
• Run your apps — query their data through their own tools, right from the agent.

Apps your agent can build in a single flow:

• a habit / workout / reading tracker with list + detail views
• a personal CRM or contacts book
• a snippet vault or bookmark manager
• a lightweight expense or invoice log
• a notes / tasks / journal app
• …any data-backed app with screens and actions you can describe in plain words.

How it works

Your client's own LLM authors the app; imperal-mcp gives it the rails. It reads the IR spec and worked examples, validates the draft against the live schema, smoke-tests it, and deploys it to the cloud — no hand-written deployment scripts, no YAML wrangling. The heavy lifting — orchestration, hosting, scaling, the kernel — is Imperal's. Your agent just describes the app; the kernel makes it real.

Quick-add to your agent

Client	One-liner
Cursor
Claude Code	/plugin marketplace add imperalcloud/imperal-mcp then /plugin install imperal-mcp@imperal
Everything else	See per-client config

Install imperal-mcp and sign in first — see below.

Install & sign in

pipx install imperal-mcp      # or: uv tool install imperal-mcp   or: pip install imperal-mcp
imperal-mcp login             # opens your browser to sign in to Imperal

Works with any Python from 3.7:

• Python 3.10 or newer — imperal-mcp runs directly on it.
• Python 3.7 – 3.9 (macOS ships 3.9, Ubuntu 20.04 has 3.8) — the install is light, and the first imperal-mcp command sets up the same release on its own Python 3.12, once (about 30–45 s, needs internet; it fetches uv to do it). Every start after that is immediate. It lives in ~/.local/share/imperal-mcp/runtime and changes nothing else on your system. Run imperal-mcp login once before adding it to your agent, so that setup is done before the agent first starts the server.

login stores credentials in ~/.imperal/credentials.json and auto-refreshes your access token — no manual token management. Sign out any time:

imperal-mcp logout

That's it — every supported client uses the same imperal-mcp binary and the same stored sign-in.

Your first app (60 seconds)

1. Install + imperal-mcp login (above), and add it to your agent.

2. Ask your agent, in plain language:

   "Build me a habit tracker — I want to add habits, mark them done each day, and see today's summary. Then deploy it."

3. Your agent authors the app, validates it, smoke-tests a function, and deploys it to your Imperal account. It comes back with the live app and its tools — ready to use.

Want to iterate? Just keep talking: "add a weekly streak view", "now build me an expense tracker too."

Per-client config

All clients use the same installed binary — imperal-mcp — and the same credentials from imperal-mcp login.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Claude Code

/plugin marketplace add imperalcloud/imperal-mcp
/plugin install imperal-mcp@imperal

Or add directly to your project .mcp.json:

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Cursor

Click the Add to Cursor button above, or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Codex (OpenAI)

Add to ~/.codex/config.toml:

[mcp_servers.imperal]
command = "imperal-mcp"

Gemini CLI

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Cline

In VS Code, add to Cline's MCP server list:

{
  "imperal": { "command": "imperal-mcp", "disabled": false }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "imperal": { "command": "imperal-mcp" }
  }
}

Goose (Block)

Add a StandardIO extension in Goose settings:

{ "type": "stdio", "name": "imperal", "cmd": "imperal-mcp", "args": [] }

Tools

Resources

Prompt

build_imperal_app — step-by-step guidance for an LLM to go from intent to a deployed app: read the spec, author the IR, validate, smoke-test, deploy.

Configuration

For CI or headless environments, set IMPERAL_TOKEN to a token from panel.imperal.io → Developer → Access tokens.

Privacy & security

You sign in with your own Imperal account (browser OAuth). Credentials live locally at ~/.imperal/credentials.json (0600) and refresh automatically — nothing is shared with third parties and there's no telemetry. Read responses are PII-masked before they reach the LLM. Full details: PRIVACY.md.

Links

• Imperal Cloud — https://imperal.io
• Panel (your apps, tokens, billing) — https://panel.imperal.io
• ICNLI (the open protocol behind it, CC BY-SA) — https://icnli.org

Development

git clone https://github.com/imperalcloud/imperal-mcp
cd imperal-mcp
pip install -e '.[dev]'
python -m pytest

License

GPL-3.0-only — see LICENSE. Releases up to 0.5.5 were published under Apache-2.0.

Built on Imperal Cloud — the AI Cloud OS. 🐝