Zetrix MCP Server

A comprehensive Model Context Protocol (MCP) server for interacting with the Zetrix blockchain. Provides 55 tools across 7 categories — HTTP RPC, WebSocket (protobuf), SDK transactions, cryptography, and smart contract development. Supports both stdio and HTTP transport modes.

Zetrix Currency Information

Native Coin: ZETRIX

• Main Unit: ZETRIX
• Base Unit: ZETA
• Conversion: 1 ZETRIX = 1,000,000 ZETA
• Gas Price: Evaluated dynamically via testTransaction

Quick Start

npx zetrix-mcp-server

Or install globally:

npm install -g zetrix-mcp-server

Guides:

• QUICKSTART.md — Get set up in 5 minutes
• EXAMPLES.md — Learn through 20+ examples
• TEST_REPORT.md — Comprehensive test results for all 55 tools

Features (56 Tools)

General (1 tool)

| Tool | Description | |---|---| | zetrix_version | Get MCP server version and network info |

HTTP RPC (16 tools)

| Tool | Description | |---|---| | zetrix_check_health | Check node health status | | zetrix_get_account | Get account info including balance and metadata | | zetrix_get_block | Get block by height | | zetrix_get_latest_block | Get latest block | | zetrix_get_transaction | Get transaction by hash | | zetrix_get_balance | Get balance in ZETA and ZETRIX | | zetrix_create_keypair | Generate new keypair (testing only) | | zetrix_get_account_base | Get basic account info | | zetrix_get_account_assets | Get asset holdings | | zetrix_get_account_metadata | Get account metadata | | zetrix_get_transaction_history | Get completed transactions | | zetrix_get_transaction_cache | Get pending transactions | | zetrix_get_ledger | Get ledger/block info | | zetrix_multi_query | Execute multiple queries | | zetrix_get_transaction_blob | Serialize transaction to hex | | zetrix_submit_transaction | Submit signed transaction |

Contract Query (2 tools)

| Tool | Description | |---|---| | zetrix_call_contract | Call contract in sandbox (read-only) | | zetrix_test_transaction | Evaluate fees without submitting |

WebSocket — Real-time (5 tools)

Uses protobuf binary encoding for communication with Zetrix nodes.

| Tool | Description | |---|---| | zetrix_ws_connect | Connect and register via protobuf CHAIN_HELLO | | zetrix_ws_submit_transaction | Submit transaction with real-time status | | zetrix_ws_subscribe_tx | Subscribe to transaction notifications | | zetrix_ws_disconnect | Disconnect from WebSocket | | zetrix_ws_status | Check connection status |

SDK Query (5 tools)

| Tool | Description | |---|---| | zetrix_sdk_create_account | Create new account | | zetrix_sdk_get_balance | Get balance via SDK | | zetrix_sdk_is_activated | Check if account is activated | | zetrix_sdk_get_nonce | Get account nonce | | zetrix_sdk_call_contract | Call contract via SDK (read-only) |

SDK Transactions (11 tools)

All transaction tools use evaluateFee (testTransaction) for dynamic gas pricing. Optional gasPrice/feeLimit overrides supported on all operations.

| Tool | Description | |---|---| | zetrix_sdk_send_gas | Send native ZETRIX to another address | | zetrix_sdk_activate_account | Activate a new account with initial balance | | zetrix_sdk_set_metadata | Set key-value metadata on an account | | zetrix_sdk_set_privilege | Set account weights, thresholds, and signers | | zetrix_sdk_issue_asset | Issue a new custom token | | zetrix_sdk_send_asset | Transfer a custom token | | zetrix_sdk_create_contract | Deploy a smart contract (with optional owner) | | zetrix_sdk_invoke_contract | Invoke contract with gas payment | | zetrix_sdk_invoke_contract_by_asset | Invoke contract with asset transfer | | zetrix_sdk_upgrade_contract | Upgrade contract code and/or transfer ownership | | zetrix_sdk_create_log | Create an on-chain event log |

Cryptography (8 tools)

| Tool | Description | |---|---| | zetrix_crypto_generate_keypair | Generate new keypair (address, private key, public key) | | zetrix_crypto_get_public_key | Derive public key from private key | | zetrix_crypto_get_address | Get address from public key | | zetrix_crypto_validate_key | Validate private key, public key, or address format | | zetrix_crypto_sign | Sign a message (hex) with a private key | | zetrix_crypto_verify | Verify a signature | | zetrix_crypto_encrypt_key | Encrypt private key with password | | zetrix_crypto_decrypt_key | Decrypt encrypted private key |

Smart Contract Development (7 tools)

| Tool | Description | |---|---| | zetrix_contract_get_chain_functions | Chain object function documentation | | zetrix_contract_get_utils_functions | Utils object function documentation | | zetrix_contract_get_structure_guide | Contract structure and ES5 patterns guide | | zetrix_contract_get_token_standard | Token standard specs (ZTP20, ZTP721, ZTP1155) | | zetrix_contract_init_dev_environment | Initialize dev project via create-zetrix-tool | | zetrix_contract_generate_advanced | Generate multi-class contract architecture | | zetrix_contract_get_testing_guide | Testing guide (TEST_INVOKE, TEST_QUERY) |

Supported Networks

| Network | HTTP RPC | WebSocket | |---|---|---| | Mainnet | https://node.zetrix.com | wss://ws-node.zetrix.com | | Testnet | https://test-node.zetrix.com | wss://test-ws-node.zetrix.com |

Configuration

Environment Variables

| Variable | Description | Default | |---|---|---| | ZETRIX_NETWORK | Network selection (mainnet or testnet) | mainnet | | ZETRIX_RPC_URL | Custom HTTP RPC endpoint (overrides network default) | — | | ZETRIX_WS_URL | Custom WebSocket endpoint (overrides network default) | — | | ZETRIX_TRANSPORT | Transport mode (stdio or http) | stdio | | ZETRIX_PORT | HTTP server port (only used when ZETRIX_TRANSPORT=http) | 3000 | | ZETRIX_PRIVATE_KEY | Default private key for signing transactions (optional, keeps key out of conversation) | — | | ZETRIX_SOURCE_ADDRESS | Default source address for transactions (optional) | — |

Secure Transactions (Recommended)

By setting ZETRIX_PRIVATE_KEY and ZETRIX_SOURCE_ADDRESS as environment variables, your private key is never exposed in the conversation. The LLM can execute transactions like "send 0.01 ZETRIX to ZTX3..." without ever seeing your key.

{
  "mcpServers": {
    "zetrix": {
      "command": "npx",
      "args": ["-y", "zetrix-mcp-server"],
      "env": {
        "ZETRIX_NETWORK": "testnet",
        "ZETRIX_PRIVATE_KEY": "your-private-key-here",
        "ZETRIX_SOURCE_ADDRESS": "your-zetrix-address-here"
      }
    }
  }
}

Note: These are optional. If not set, the LLM will need to ask for or be given the private key and source address in the conversation. If set, they are used as defaults — you can still override them per-tool call if needed.

Claude Code (CLI)

Add the MCP server directly from the command line:

Mainnet:

claude mcp add zetrix-mainnet -s user -- npx -y zetrix-mcp-server -e ZETRIX_NETWORK=mainnet

Testnet:

claude mcp add zetrix-testnet -s user -- npx -y zetrix-mcp-server -e ZETRIX_NETWORK=testnet

With custom RPC and WebSocket URLs:

claude mcp add zetrix-testnet -s user -- npx -y zetrix-mcp-server \
  -e ZETRIX_NETWORK=testnet \
  -e ZETRIX_RPC_URL=https://your-node.example.com \
  -e ZETRIX_WS_URL=wss://your-ws-node.example.com

Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Windows (Microsoft Store): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Testnet:

{
  "mcpServers": {
    "zetrix": {
      "command": "npx",
      "args": ["-y", "zetrix-mcp-server"],
      "env": {
        "ZETRIX_NETWORK": "testnet"
      }
    }
  }
}

Mainnet:

{
  "mcpServers": {
    "zetrix": {
      "command": "npx",
      "args": ["-y", "zetrix-mcp-server"],
      "env": {
        "ZETRIX_NETWORK": "mainnet"
      }
    }
  }
}

Both networks (mainnet + testnet):

{
  "mcpServers": {
    "zetrix-mainnet": {
      "command": "npx",
      "args": ["-y", "zetrix-mcp-server"],
      "env": {
        "ZETRIX_NETWORK": "mainnet"
      }
    },
    "zetrix-testnet": {
      "command": "npx",
      "args": ["-y", "zetrix-mcp-server"],
      "env": {
        "ZETRIX_NETWORK": "testnet"
      }
    }
  }
}

With custom RPC and WebSocket URLs:

{
  "mcpServers": {
    "zetrix": {
      "command": "npx",
      "args": ["-y", "zetrix-mcp-server"],
      "env": {
        "ZETRIX_NETWORK": "testnet",
        "ZETRIX_RPC_URL": "https://your-node.example.com",
        "ZETRIX_WS_URL": "wss://your-ws-node.example.com"
      }
    }
  }
}

After saving the config file, restart Claude Desktop for changes to take effect.

Note: ZETRIX_RPC_URL and ZETRIX_WS_URL override the default endpoints for the selected network. You can override just one or both. If not set, the defaults from the table above are used.

HTTP Transport (API Server)

Run the MCP server as an HTTP API server using the Streamable HTTP transport. This allows remote MCP clients to connect over the network.

Start the server (defaults to mainnet):

ZETRIX_TRANSPORT=http ZETRIX_PORT=3000 npx zetrix-mcp-server

With testnet:

ZETRIX_TRANSPORT=http ZETRIX_PORT=3000 ZETRIX_NETWORK=testnet npx zetrix-mcp-server

Endpoints:

| Endpoint | Method | Description | |---|---|---| | /mcp | POST | MCP protocol endpoint (Streamable HTTP) | | /health | GET | Health check — returns { status, version, network } |

Connect from an MCP client:

{
  "mcpServers": {
    "zetrix": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Both networks (mainnet + testnet):

Run two servers on different ports:

ZETRIX_TRANSPORT=http ZETRIX_PORT=3000 ZETRIX_NETWORK=mainnet npx zetrix-mcp-server &
ZETRIX_TRANSPORT=http ZETRIX_PORT=3001 ZETRIX_NETWORK=testnet npx zetrix-mcp-server &

Then configure your MCP client:

{
  "mcpServers": {
    "zetrix-mainnet": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    },
    "zetrix-testnet": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

Note: The HTTP transport uses the MCP Streamable HTTP specification. Any MCP client that supports StreamableHTTP transport can connect to it.

Server logs:

The server logs to stderr. To view logs, run in the foreground or redirect to a file:

# Foreground — logs show directly in terminal
ZETRIX_TRANSPORT=http ZETRIX_PORT=3000 npx zetrix-mcp-server

# Background with logs to file
ZETRIX_TRANSPORT=http ZETRIX_PORT=3000 npx zetrix-mcp-server 2> server.log &
tail -f server.log

Development

Project Structure

zetrix-mcp-server/
├── src/
│   ├── index.ts                  # MCP server (55 tool definitions + handlers)
│   ├── zetrix-client.ts          # HTTP RPC client
│   ├── zetrix-sdk.ts             # SDK wrapper (11 transaction operations)
│   ├── zetrix-websocket.ts       # WebSocket client (protobuf binary)
│   ├── zetrix-encryption.ts      # Crypto operations
│   ├── zetrix-contract-docs.ts   # Contract documentation
│   └── zetrix-contract-generator.ts # Contract code generator
├── tests/
│   ├── test-server.js            # HTTP RPC tests
│   ├── test-sdk.js               # SDK tests
│   └── test-encryption.js        # Crypto tests
├── docs/
│   ├── TEST_REPORT.md            # Comprehensive test results
│   ├── DEVELOPER_GUIDE.md        # Developer documentation
│   ├── ZETRIX_CONTRACT_DEVELOPMENT_RULES.md
│   ├── QUICKSTART.md             # 5-minute setup guide
│   └── EXAMPLES.md               # 20+ usage examples
└── dist/                         # Compiled output

Build

npm install
npm run build

Test

npm test                           # HTTP RPC tests
ZETRIX_NETWORK=testnet npm test    # Run on testnet
npm run test:sdk                   # SDK tests
npm run test:encryption            # Crypto tests

License

MIT