How do I use genlayer-cli-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@genlayer-cli-mcp Lint my contract and deploy it on localnet" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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:

Use privateKey from the tool input if valid.
Otherwise use private key from MCP config env if valid.
Otherwise generate a new private key.
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.

genlayer-cli-mcp

GenLayer CLI MCP

Requirements

MCP Config

Local Development

Tools

`check_tools`

`genlayer`

`genvm_lint`

`genlayer_deploy`

Agent Setup Examples

Codex

Antigravity

Claude Code

Security

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API