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