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

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:

Scope	Location
User	`~/.claude/mcp.json`
Project	`.mcp.json`

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

Codex

CLI:

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

Config file:

Scope	Location
Global	`~/.codex/config.toml`
Project	`.codex/config.toml`

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

OpenCode

Config file:

Scope	Location
User	`~/.opencode/opencode.json` (Linux/macOS)
Workspace	`opencode.json` (project root)

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

Factory Droid

CLI:

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

Config file:

Scope	Location
User	`~/.factory/mcp.json`
Project	`.factory/mcp.json`

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

Antigravity

Uses a Powers system with custom configuration.

Config file:

Scope	Location
Workspace	`.antigravity/powers/` or project config

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:

Scope	Location
User	`~/.cursor/mcp.json`
Project	`.cursor/mcp.json`

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

Amp Code

CLI:

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

Config file:

Scope	Location
User	`~/.config/amp/settings.json` (macOS/Linux)
Workspace	`.amp/settings.json`

{
  "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:

Scope	Location
User	`~/.config/Code/User/mcp.json` (Linux)
Workspace	`.vscode/mcp.json`

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

Windsurf

Config file:

Scope	Location
User	`~/.codeium/windsurf/mcp_config.json`

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

Kiro

Config file:

Scope	Location
User	`~/.kiro/settings/mcp.json`
Workspace	`.kiro/settings/mcp.json`

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

Kilo Code

Config file:

Scope	Location
User	`~/.config/Kilo Code/User/mcp.json`
Project	`.vscode/mcp.json`

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

Cline

Config file:

Scope	Location
User	`cline_mcp_settings.json` (in config dir)

{
  "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.

Variable	Default	Description
`JUNO_MCP_CHAR_LIMIT`	`25000`	Max characters returned in a single tool response (truncates beyond)
`JUNO_MCP_TIMEOUT`	`120000`	Default subprocess timeout in milliseconds
`JUNO_MCP_NETWORK_TIMEOUT`	`300000`	Timeout for network-bound operations (deploy, publish, upgrade) in ms
`JUNO_MCP_DEBUG`	`false`	When `true`, logs internal errors to stderr (silent catches, notifications)
`JUNO_MCP_STATE_SECRET`	random	HMAC key (>=32 bytes) for MRTR `requestState`; set to survive restarts (default per-process random invalidates in-flight flows)

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

Scaffolds a Vite project (React, Next.js, Svelte, Angular, or Vue)
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

Domain	Tools
Identity	`juno_version`, `juno_login`, `juno_run`, `juno_status`, `juno_auth_status`
Config	`juno_config_init`, `juno_config_apply`, `juno_create_project`
Hosting	`juno_hosting_deploy`, `juno_hosting_clear`, `juno_hosting_prune`
Functions	`juno_functions_build`, `juno_functions_eject`, `juno_functions_publish`, `juno_functions_upgrade`
Changes	`juno_changes_list`, `juno_changes_apply`, `juno_changes_reject`
Docs	`juno_docs`

Key Parameters

Several tools support optional parameters for enhanced reliability and UX:

Parameter	Type	Tools	Description
`retry`	`boolean`	deploy, publish, upgrade	Retry on transient network failures with exponential backoff when enabled. Attempts are set by `maxRetries`
`maxRetries`	`number`	deploy, publish, upgrade	Maximum retry attempts when `retry` is enabled (0-10, default 3; backoff 1s → 2s → 4s capped at 10s)
`batch`	`number`	deploy, prune	Files processed per batch (deploy default 50, prune default 100). For `deploy`, capped at the detected `source`-dir file count when found (juno.config `source`), so small projects don't waste 50-way parallelism
`progress`	`boolean`	deploy, publish, upgrade	Stream real-time progress updates during long-running operations (build status + upload batch progress)
`streamLogs`	`boolean`	deploy, publish, upgrade	Stream raw stdout/stderr lines as MCP `notifications/message` events. Independent from `progress`
`writeFile`	`boolean`	`juno_config_init`	Write the config file directly to disk instead of returning text for preview

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/:

License

MIT

Name		Name	Last commit message	Last commit date
.changeset		.changeset
.claude		.claude
.vscode		.vscode
.zed		.zed
docs/adr		docs/adr
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
.nwron		.nwron
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
README.md		README.md
TODO.md		TODO.md
biome.jsonc		biome.jsonc
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.e2e.config.ts		vitest.e2e.config.ts

Navigation Menu

Repository files navigation

junobuild-mcp-server

Features

Client Setup

Claude Code

Codex

OpenCode

Factory Droid

Antigravity

Cursor

Amp Code

VSCode

Windsurf

Kiro

Kilo Code

Cline

Protocol Versions

Authenticate the Juno CLI

Environment Variables

HTTP Mode

Server Tuning

Documentation Access

Tools

Key Parameters

Prerequisites

Development

Coverage thresholds

Publishing

Architecture

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

junobuild-mcp-server

Features

Client Setup

Claude Code

Codex

OpenCode

Factory Droid

Antigravity

Cursor

Amp Code

VSCode

Windsurf

Kiro

Kilo Code

Cline

Protocol Versions

Authenticate the Juno CLI

Environment Variables

HTTP Mode

Server Tuning

Documentation Access

Tools

Key Parameters

Prerequisites

Development

Coverage thresholds

Publishing

Architecture

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages