junobuild-mcp-server

Unofficial MCP server for Juno. Not affiliated with or endorsed by the Juno team.

Manage satellites, hosting, serverless functions, changes and more through any MCP-compatible client. Includes a built-in documentation tool to access Juno's official guides and references.

Features

• 19 tools across 6 domains — CLI coverage for identity, config, hosting, functions, changes, and documentation

• Progress streaming — long-running operations (deploy, publish, upgrade) emit real-time progress updates via MCP notifications/progress

• Log streaming — streamLogs: true mirrors raw stdout/stderr lines as MCP notifications/message events, independent of progress

• Automatic retry — network-dependent operations can retry on transient failures with exponential backoff

• CLI binary caching — resolves juno binary path once, eliminating npx overhead on every call

• CLI version check — verifies installed @junobuild/cli meets the minimum supported version on first call

• Structured error parsing — common CLI failures (auth, network, missing config) surface as actionable messages

• Config file writing — juno_config_init can write config files directly to disk

• Auth verification — juno_auth_status wraps juno whoami for read-only identity checks

• Docs caching — documentation responses backed by an LRU cache (50 entries, 1 h TTL)

• Tunable limits — character limit, default timeout, and network timeout overridable via env vars

Related MCP server: docsbook-mcp

Client Setup

Choose your AI coding agent below for specific setup instructions.

Claude Code

CLI (recommended):

claude mcp add junobuild npx -y junobuild-mcp-server

Config file:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Codex

CLI:

codex mcp add junobuild -- npx -y junobuild-mcp-server

Config file:

[mcp_servers.junobuild]
command = "npx"
args = ["-y", "junobuild-mcp-server"]

OpenCode

Config file:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Factory Droid

CLI:

droid mcp add junobuild npx -y junobuild-mcp-server

Config file:

{
  "mcpServers": {
    "junobuild": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Antigravity

Uses a Powers system with custom configuration.

Config file:

Add the MCP server configuration to your Power's mcp.json:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Note: See Antigravity MCP documentation for full Power setup.

Cursor

Config file:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Amp Code

CLI:

amp mcp add junobuild -- npx -y junobuild-mcp-server

Config file:

{
  "amp.mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Note: Workspace MCP servers require approval via amp mcp approve <server-name>.

VSCode

Config file:

{
  "servers": {
    "junobuild": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Windsurf

Config file:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Kiro

Config file:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Kilo Code

Config file:

{
  "servers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Cline

Config file:

{
  "mcpServers": {
    "junobuild": {
      "command": "npx",
      "args": ["-y", "junobuild-mcp-server"]
    }
  }
}

Protocol Versions

The server builds against the 2026-07-28 protocol revision (@modelcontextprotocol/server@2) and serves both protocol eras from one toolset: 2025-era clients (e.g. Claude Desktop mid-2026) still negotiate via initialize; 2026-07-28 clients via server/discover. No flag needed — era detection is automatic per request.

Features we deliberately do not adopt (deprecated or out of scope for a CLI wrapper):

• Roots and Sampling — the server is a tool runner; input is explicit tool parameters and MRTR (input_required) elicitation, not implicit sampling.

• logging/setLevel (2026-era) — log gating is per-request _meta.logLevel; 2025-era sessions still get logging/setLevel via the SDK.

• HTTP+SSE endpoint — the transport is Streamable HTTP with JSON responses; the deprecated SSE-across-connections mode is not served.

MRTR: juno_login asks for the credentials-encryption passphrase via input_required (the model answers the embedded form); 2025-era clients get the same flow via the SDK's legacy shim.

Authenticate the Juno CLI

The server wraps @junobuild/cli, which must be installed and authenticated:

npm i -g @junobuild/cli
juno login

For non-interactive environments (CI, headless), set the JUNO_TOKEN environment variable instead of running juno login. Tools that touch Juno state additionally accept mode and profile parameters to select an environment and identity per call.

Environment Variables

For non-interactive environments (CI, headless), authenticate using environment variables:

export JUNO_TOKEN="your-juno-token"

HTTP Mode

The server defaults to stdio. Set JUNO_MCP_TRANSPORT=http to serve over Streamable HTTP instead (default port 3000, bound to 127.0.0.1; override with JUNO_MCP_PORT):

JUNO_MCP_TRANSPORT=http JUNO_MCP_PORT=3100 node dist/main.js

The HTTP mode is stateless and serves both protocol eras from the same toolset as stdio: 2026-07-28 clients negotiate via server/discover (modern requests must send the Mcp-Method/Mcp-Name headers), 2025-era clients via initialize. Portable to any web client or load balancer.

Smoke test with curl:

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Mcp-Method: server/discover" \
  -H "Mcp-Name: curl" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"0"}}}}'

Security: HTTP mode binds to localhost only and is unauthenticated — a local dev mode. Do not expose it to the network or pair it with a public tunnel without adding an auth layer (OAuth / reverse-proxy auth).

Server Tuning

Override defaults to tune resource limits without rebuilding. Values must be positive integers; invalid values fall back to defaults.

Note: The juno_create_project tool does NOT use the interactive create-juno CLI. Instead it:

1. Scaffolds a Vite project (React, Next.js, Svelte, Angular, or Vue)

2. Creates a juno.config.ts file

This allows fully non-interactive project creation.

Documentation Access

The juno_docs tool fetches documentation directly from the GitHub repo, with responses cached for 1 hour:

juno_docs({ topic: "build_datastore" })        → Datastore guide
juno_docs({ topic: "build_authentication" })   → Authentication overview
juno_docs({ topic: "reference_cli" })        → CLI reference
juno_docs({ topic: "guides_local_development" }) → Local development guide

Topic keys use underscore naming matching folder hierarchy: build_<feature>, reference_cli_<command>, guides_<framework>. Full enumeration of all 159 topics lives in src/schemas/docs.ts (TOPICS map).

Tools

Key Parameters

Several tools support optional parameters for enhanced reliability and UX:

Prerequisites

• Node.js >= 20

• @junobuild/cli >= 0.15.0 — installed and authenticated (not needed for juno_version or juno_docs). Minimum version enforced on first call via checkCliVersion (src/constants.ts MIN_CLI_VERSION). Bypass with JUNO_SKIP_VERSION_CHECK=true.

• Juno project with juno.config.ts/js/json (for config/hosting operations)

Development

npm run build           # Compile TypeScript to dist/
npm run dev             # Watch mode (development)
npm run start           # Run compiled dist/main.js
npm run clean           # Remove dist/
npm test                # Run unit tests
npm run test:coverage   # Run tests with coverage report (v8 provider)

Coverage thresholds

The suite enforces the following minimum coverage (configured in vitest.config.ts):

• Lines: 80%

• Statements: 80%

• Functions: 80%

• Branches: 75%

Coverage reports are written to coverage/ (html, lcov, json, plus text summary).

Publishing

npm run changeset    # Create a changeset (version bump + changelog entry)
npm run version      # Apply changesets → bump version
npm run release      # Publish to npm

Architecture

The server is a thin wrapper around the Juno CLI (@junobuild/cli): every tool builds a command + flags, spawns the CLI via child_process, and formats the result. Long-running tools (deploy, publish, upgrade) support three execution strategies — simple, retry, and streaming (progress + log notifications).

Transports (chosen at startup via JUNO_MCP_TRANSPORT):

• stdio (default) — one process per client over stdin/stdout

• Streamable HTTP (JUNO_MCP_TRANSPORT=http, port 3000 / JUNO_MCP_PORT, 127.0.0.1) — Streamable HTTP endpoint, many clients per process

Both serve both protocol eras from the same code: 2025-era clients via initialize, 2026-07-28 clients via server/discover. Build file is src/main.ts (entry, transport pick); src/index.ts is a side-effect-free buildServer() factory. Auth via juno_login (MRTR passphrase flow) uses HMAC-signed request state.

Key design decisions are documented as ADRs in docs/adr/:

• ADR-001 — Wrap the Juno CLI instead of the API

• ADR-002 — Execution strategy pattern (simple / retry / streaming)

• ADR-003 — Context capability system

• ADR-004 — Docs caching strategy

• ADR-005 — SDK v2 stateless migration (2026-07-28 spec)

License

MIT