Nexos MCP — let your AI do the setup

The Nexos MCP server gives Claude Code, Cursor and any other MCP-aware AI agent the tools to drive the full project-setup loop from inside your editor: detect your framework, generate the right Dockerfile, create the project, wire up secrets, and walk you through the GitHub webhook. The AI hits the friction points instead of you.

# 1. Add the MCP server (one-time)
claude mcp add nexos -- npx -y @nexos.rs/mcp

# 2. In your repo, ask Claude:
> Set this repo up on Nexos.

What the MCP does

• Detects your framework (Next.js / Django / Rails / Go / …), the services you need (postgres, redis, mongo), your migration tool, and the env vars your code references.
• Generates a Dockerfile.nexos tuned for your stack plus a complete nexos.yaml with build config, addons, ports, and a sensible on_deploy hook.
• Creates the Nexos project, or recognizes that one already exists for this repo (no accidental duplicates).
• Configures managed addons and bulk-imports env vars — including reading your .env.example to figure out which keys to ask you for.
• Walks you through the GitHub webhook setup with the exact URL, secret, and events to tick. The only manual step.
• Observes deploys — reads logs, lists environments, and can diagnose build failures itself instead of asking you to copy-paste error messages.

Installation

Claude Code (terminal)

claude mcp add nexos -- npx -y @nexos.rs/mcp

For self-hosted Nexos, pass NEXOS_API_URL as an env var with -e (before the -- separator):

claude mcp add nexos \
  -e NEXOS_API_URL=https://api.your-nexos.example.com \
  -- npx -y @nexos.rs/mcp

Claude Desktop / Cursor / generic MCP client

Add the server to your client's MCP config (usually ~/.claude/claude_desktop_config.json or a project-local .mcp.json):

{
  "mcpServers": {
    "nexos": {
      "command": "npx",
      "args": ["-y", "@nexos.rs/mcp"]
    }
  }
}

Authentication

Two flows are supported:

1. Device code (recommended) — Ask Claude to nexos_login. The MCP prints a short 8-character code and a one-click URL. You open the URL, sign in to Nexos, paste the code, and click Approve. Claude picks up a fresh API key automatically.
2. API key — Generate one in Account → API Keys and either pass it to nexos_login directly, or set NEXOS_API_KEY in the MCP's env (good for CI).

Credentials are stored at ~/.nexos/credentials.json with0600 file mode. Revoke any key at any time from the same settings page.

Typical first-run conversation

From a Claude Code session in your repo:

> Set this repo up on Nexos.

Claude → nexos_status
  → "Not logged in. Starting device-code flow..."
Claude → nexos_login
  → prints: "Open https://app.nexos.rs/auth/cli?code=ABCD-WXYZ"
  → waits for you to click Approve in the browser
  → "Logged in as you@github."

Claude → nexos_detect
  → "Detected nextjs on port 3000. Suggested addons: postgres.
     Suggested onDeployCommand: npx prisma migrate deploy.
     12 env vars referenced; 3 not in .env.example — I'll ask you."

Claude → "I'd like to write Dockerfile.nexos and nexos.yaml. OK?"

You   → "yes"

Claude → nexos_generate_config { overwrite: false }
  → "Wrote Dockerfile.nexos and nexos.yaml."

Claude → nexos_create_project_from_yaml
  → "Project 'my-app' created."

Claude → "What's the value of STRIPE_SECRET_KEY?"
You   → "sk_test_..."
Claude → nexos_set_env_vars { isSecret: true }
  → "Set 3 env vars (1 created, 2 updated)."

Claude → nexos_get_webhook_info
  → prints the Payload URL, Secret, and the 3 events to tick.

You   → (paste into GitHub → Add webhook → green checkmark)

Claude → "All set. Push your branch:"
  →   git add Dockerfile.nexos nexos.yaml
  →   git commit -m "wire up nexos"
  →   git push -u origin main

Tool reference

Full list at npmjs.com/package/@nexos.rs/mcp. Key tools:

• nexos_status, nexos_login, nexos_logout
• nexos_detect (read-only), nexos_generate_config (writes Dockerfile + YAML)
• nexos_create_project, nexos_create_project_from_yaml, nexos_apply_yaml, nexos_export_yaml
• nexos_set_env_vars, nexos_import_env_file
• nexos_addon_catalog, nexos_enable_addon
• nexos_get_webhook_info
• nexos_trigger_deploy, nexos_list_environments, nexos_get_deployment_logs

Where to go next

• nexos.yaml — the config the MCP generates.
• AI Agent Spec — what the MCP knows about your stack.
• Getting Started — the manual flow, if you prefer.