GenLayer CLI MCP

MCP server for AI agents that need to work with GenLayer projects.

It exposes:

• genlayer: full access to the GenLayer CLI
• genvm_lint: access to genvm-lint
• genlayer_deploy: deploys contracts with genlayer-js
• check_tools: verifies local tool availability and private key config

The server uses stdio transport and executes commands with spawn(command, args).

Requirements

• Node.js 18+
• GenLayer CLI available on PATH
• GenVM linter available on PATH

Install the external tools:

npm install -g genlayer
py -3.12 -m pip install genvm-linter

Check them:

genlayer --version
genvm-lint --version

MCP Config

If this package is published to npm:

{
  "mcpServers": {
    "genlayer-cli": {
      "command": "npx",
      "args": ["-y", "genlayer-cli-mcp"],
      "env": {
        "GENLAYER_PRIVATE_KEY": "0x_your_private_key_here"
      }
    }
  }
}

If running from this repository:

{
  "mcpServers": {
    "genlayer-cli": {
      "command": "node",
      "args": ["E:\\genlayer-cli-mcp\\dist\\index.js"],
      "env": {
        "GENLAYER_PRIVATE_KEY": "0x_your_private_key_here"
      }
    }
  }
}

Accepted private key env names:

• GENLAYER_PRIVATE_KEY
• GENLAYER_PRV_KEY
• GENLAYER_PRIVKEY
• PRIVATE_KEY

The private key may be either 0x plus 64 hex characters or raw 64 hex characters. If the configured key is missing or invalid, genlayer_deploy generates a new private key and deploys with it in the same tool call. When a new key is generated, the response includes it so you can save it.

Local Development

cd E:\genlayer-cli-mcp
npm install
npm run build
npm run smoke

Run the server:

node E:\genlayer-cli-mcp\dist\index.js

Package locally:

npm pack

Publish to npm:

npm login
npm publish --access public

Tools

check_tools

Checks node, genlayer, python, genvm-lint, and private key config.

Example AI prompt:

Use MCP tool check_tools from genlayer-cli.

genlayer

Runs genlayer <args...> with full command access.

Example:

{
  "args": ["--version"]
}

Example deploy through the raw CLI:

{
  "args": [
    "deploy",
    "--contract",
    "E:\\path\\to\\contract.py",
    "--rpc",
    "http://localhost:4000/api"
  ],
  "timeoutMs": 120000
}

genvm_lint

Runs genvm-lint <args...>.

Example:

{
  "args": ["check", "E:\\path\\to\\contract.py"],
  "timeoutMs": 120000
}

genlayer_deploy

Deploys an Intelligent Contract through genlayer-js.

This is the recommended deploy tool for AI agents because it handles private key fallback:

1. Use privateKey from the tool input if valid.
2. Otherwise use private key from MCP config env if valid.
3. Otherwise generate a new private key.
4. Deploy with the selected/generated private key immediately.

Example:

{
  "contractPath": "E:\\path\\to\\contract.py",
  "chain": "localnet",
  "rpcUrl": "http://localhost:4000/api",
  "autoFundLocalnet": true,
  "waitForReceipt": true,
  "receiptStatus": "ACCEPTED",
  "timeoutMs": 120000
}

Optional fields:

{
  "privateKey": "0x...",
  "args": [],
  "kwargs": {},
  "cwd": "E:\\project",
  "leaderOnly": false,
  "consensusMaxRotations": 5,
  "initializeConsensus": true,
  "fundAmount": 10,
  "receiptRetries": 50,
  "receiptIntervalMs": 5000,
  "exposePrivateKey": false
}

Supported chains:

• localnet
• studionet
• testnetAsimov
• testnetBradbury

Agent Setup Examples

Use the same MCP server definition for coding agents that support MCP over stdio. Replace the private key with your own testnet/local key, or leave it invalid if you want genlayer_deploy to generate a fresh key during deploy.

Codex

Add this MCP server to your Codex MCP configuration:

{
  "mcpServers": {
    "genlayer-cli": {
      "command": "npx",
      "args": ["-y", "genlayer-cli-mcp"],
      "env": {
        "GENLAYER_PRIVATE_KEY": "0x_your_private_key_here"
      }
    }
  }
}

Suggested Codex prompt:

Use MCP tool check_tools from genlayer-cli and tell me whether deploy can use the configured private key.

Then lint my GenLayer contract with genvm_lint.

If lint passes, deploy it with genlayer_deploy using:
{
  "contractPath": "E:\\path\\to\\contract.py",
  "chain": "localnet",
  "rpcUrl": "http://localhost:4000/api",
  "autoFundLocalnet": true,
  "waitForReceipt": true,
  "receiptStatus": "ACCEPTED"
}

Antigravity

Add the MCP server in Antigravity's MCP settings:

{
  "mcpServers": {
    "genlayer-cli": {
      "command": "npx",
      "args": ["-y", "genlayer-cli-mcp"],
      "env": {
        "GENLAYER_PRIVATE_KEY": "0x_your_private_key_here"
      }
    }
  }
}

Suggested Antigravity prompt:

Use the genlayer-cli MCP server.

First call check_tools.
Then run genvm_lint on:
{
  "args": ["check", "E:\\path\\to\\contract.py"]
}

If the contract is valid, call genlayer_deploy. If the configured MCP private key is invalid, let the MCP tool generate a new private key and deploy with it automatically.

Claude Code

Add the server with Claude Code's MCP add command:

claude mcp add genlayer-cli -- npx -y genlayer-cli-mcp

If your Claude Code setup supports environment variables in MCP config, add:

{
  "GENLAYER_PRIVATE_KEY": "0x_your_private_key_here"
}

Alternative local-source command:

claude mcp add genlayer-cli -- node E:\genlayer-cli-mcp\dist\index.js

Suggested Claude Code prompt:

Use the genlayer-cli MCP server.

1. Call check_tools.
2. Run genvm_lint for E:\path\to\contract.py.
3. If lint succeeds, deploy with genlayer_deploy.
4. If the private key in MCP config is missing or invalid, generate a new private key and deploy with that generated key in the same tool call.

Arguments:
{
  "contractPath": "E:\\path\\to\\contract.py",
  "chain": "localnet",
  "rpcUrl": "http://localhost:4000/api",
  "autoFundLocalnet": true,
  "waitForReceipt": true,
  "receiptStatus": "ACCEPTED"
}

Security

This MCP server intentionally exposes full GenLayer command access. AI agents can run state-changing commands such as deploy, write, up, stop, and init.

Do not put a mainnet private key in MCP config unless you trust the AI client and all enabled tools.