@venelx/mcp

An MCP (Model Context Protocol) server that lets AI assistants (Claude Code, Cursor, Kimi Code, and any MCP-compatible client) operate the Venelx CI/CD platform through its REST API: list projects, trigger builds, check build status, tail logs, list artifacts and workers, and diagnose signing / GitHub access.

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, no copy-pasting):

    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 — no VENELX_TOKEN env var needed.
  • Manual token — create one in the Venelx dashboard at Account → API tokens: , then pass it as VENELX_TOKEN (see Configuration below).

Token scopes

Tokens look like vx_.... Treat them like passwords — pass them via environment variables, never commit them.

Configuration

Install & run

Straight from GitHub (latest source, no npm release needed)

npx can run the server directly from the VenelX/mcp repo — npm clones it and builds it (prepare) on first run:

claude mcp add venelx -e VENELX_TOKEN=vx_... -- npx -y github:VenelX/mcp

Pin a release with a tag (github:VenelX/mcp#v0.1.2); without one you get main.

Claude Code

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

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 as above — 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"
      }
    }
  }
}

Local development

git clone  && cd venelx-mcp
npm install
npm run build

Then point your MCP client config at the local build:

{
  "mcpServers": {
    "venelx": {
      "command": "node",
      "args": ["/path/to/venelx-mcp/dist/index.js"],
      "env": {
        "VENELX_TOKEN": "vx_..."
      }
    }
  }
}

Tools

Onboarding and workers

Set up a project with one prompt

Paste this into your MCP client from the repo you want to build (also in the docs at https://docs.venelx.com/mcp):

Set up this repository on Venelx using the venelx MCP server. Run detect_project_setup and show me
the result, then create_project with the detected values, set env vars (ask me for values; never read
my .env), sync gitignored build files and signing only after I approve, make sure a worker is online
(worker_install_command if not), then trigger_build and follow the logs. Never print secrets.

Local signing sync — limitations

• iOS only supports one extra provisioning profile per project today (whichever sub-bundle-ID extension is found locally — typically a share extension). If your app has multiple extension targets (share extension and widget, for example), only one gets synced; sync_local_ios_signing’s response lists every extension bundle ID it found so you can see what was skipped. Supporting arbitrary extension counts needs a larger change to how Venelx stores iOS signing credentials — not done yet.
• sync_local_ios_signing exports every codesigning identity in your login Keychain into one .p12 (macOS’s security export doesn’t cleanly filter to a single identity) and refuses to run at all if no Distribution identity is present, since an AppStore/AdHoc profile without a matching Distribution cert+key can’t actually sign a release build.

Troubleshooting

• 401 Authentication failed — VENELX_TOKEN is missing, wrong, or revoked. 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.

License

MIT