Skip to content

nami2111/junobuild-mcp

BranchesTags

Repository files navigation

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

  • 18 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"]
    }
  }
}

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"

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)

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

Domain Tools
Identity juno_version, 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 Automatically retry on transient network failures (up to 3 attempts with exponential backoff: 1s → 2s → 4s)
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 >= 18
  • @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/index.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

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

License

MIT

About

MCP server for Juno (junobuild) - manage satellites, hosting, functions, snapshots and more

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages