MCP Server

@venelx/mcp is an MCP (Model Context Protocol) server that lets AI assistants — Claude Code, Cursor, Kimi Code, and any MCP-compatible client — operate the Venelx platform through its REST API: list projects, trigger builds, check build status, tail logs, list artifacts and workers, diagnose code-signing / GitHub access, and sync local iOS/Android signing credentials.

The server talks to the Venelx API over HTTPS and to your AI client over stdio.

Prerequisites

• Node.js ≥ 18
• A Venelx account with at least one project
• A token — either of:
  • Browser login (recommended, nothing to copy-paste) — run npx @venelx/mcp login
  • Manual token — create one in the dashboard at Account → API tokens: app.venelx.com/account/tokens

Browser login

npx @venelx/mcp login

Opens app.venelx.com in your browser. Approve access there and the token is saved to ~/.venelx/mcp-token — the server picks it up automatically, so your MCP client config doesn't need a VENELX_TOKEN env var at all.

Token scopes

Tokens look like vx_.... Treat them like passwords — pass them via environment variables, never commit them. See API tokens for the full lifecycle.

Configuration

Install & run

Claude Code

claude mcp add venelx --env VENELX_TOKEN=vx_... -- npx -y @venelx/mcp

Skip the --env VENELX_TOKEN=... entirely if you've already run npx @venelx/mcp login.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "venelx": {
      "command": "npx",
      "args": ["-y", "@venelx/mcp"],
      "env": {
        "VENELX_TOKEN": "vx_..."
      }
    }
  }
}

Kimi Code / generic MCP client

Same shape — add to your client's MCP JSON config:

{
  "mcpServers": {
    "venelx": {
      "command": "npx",
      "args": ["-y", "@venelx/mcp"],
      "env": {
        "VENELX_TOKEN": "vx_...",
        "VENELX_API_URL": "https://api.venelx.com"
      }
    }
  }
}

Build from source

The MCP server is open source: github.com/VenelX/mcp. Most people just use npx -y @venelx/mcp.

Tools

Onboarding and workers

Build and test configuration

These tools edit what the dashboard edits. Updates read the current value and merge, so a partial update never wipes the rest.

Set up a project automatically

Open the repository you want to build in Claude Code, Cursor or any MCP client with the Venelx server installed, and paste this prompt. The assistant scans the repo, creates the Venelx project, and walks you through the rest, asking before it uploads anything sensitive.

Set up this repository on Venelx using the venelx MCP server.

1. Run detect_project_setup on this repo and show me what it found (GitHub URL, branch,
   build stack, platforms, app folder). If there is no GitHub remote, stop and tell me:
   Venelx builds from GitHub.
2. Call create_project with the detected name, githubUrl, buildStack and defaultBranch.
   If the stack is ambiguous, ask me which one.
3. If the app is not in the repo root, call update_project_settings with the rootDirectory.
4. For every key in envKeys, ask me for the value (do not read my .env file) and set it
   with set_env_var. Mark secrets as secret.
5. If detect_project_setup lists gitignored build files (google-services.json, keystore,
   local.properties), upload them with sync_build_files, after telling me which files.
6. Signing: run discover_local_ios_signing and discover_local_android_signing, show me
   what was found, and only sync after I say yes. Then check signing_status.
7. Run list_workers. If no worker is online, call worker_install_command and give me the
   command to run on the build machine, then wait for me to confirm it is paired.
8. Call trigger_build for the main platform, follow it with build_status and tail_logs, and
   if it fails, diagnose it. Fix build configuration with get_build_config and
   update_build_commands; do not change my source code unless I ask.
9. Finish with a short summary: project id, what was configured, build result, anything left.

Rules: never print token values or secret values; ask before any step that uploads
credentials; stop and ask if something is unclear.

The same prompt is available as plain text at docs.venelx.com/ai-setup-prompt.txt, and on the Set up with AI page.

Before you start

• Connect GitHub to your Venelx account (Account → GitHub). create_project needs it to link the repository.
• Use a token with the write scope (npx @venelx/mcp login grants it). Read-only tokens can scan and inspect but cannot create or change anything.
• Push the repo to GitHub first. The scan reads the local origin remote.

Troubleshooting

• 401 Authentication failed — VENELX_TOKEN is missing, wrong, or revoked. Run npx @venelx/mcp login again, or create a new token at Account → API tokens and update your MCP config.
• 403 Forbidden on trigger_build — your token only has the read scope. Create a token with the write scope.
• Could not reach the Venelx API (ECONNREFUSED / ENOTFOUND) — the API base URL is unreachable. Check VENELX_API_URL (defaults to https://api.venelx.com) and your network.
• Nothing happens / no output — MCP servers speak JSON-RPC on stdout; run it through your MCP client, not directly in a terminal. Diagnostics are printed to stderr.