Zetrix MCP Server

A comprehensive Model Context Protocol (MCP) server for interacting with the Zetrix blockchain through Claude Desktop.

💰 Zetrix Currency Information

Native Coin: ZETRIX

• Main Unit: ZETRIX
• Micro Unit: ZETA
• Conversion: 1 ZETRIX = 1,000,000 ZETA
• Standard Gas Price: 5 ZETA per transaction

🚀 Quick Start

New to this? Start here:

• QUICKSTART.md - Get set up in 5 minutes
• EXAMPLES.md - Learn through 20+ examples
• SETUP_COMPLETE.md - Complete overview

Installation:

npm install
npm run build
npm run setup    # Interactive setup wizard

Then restart Claude Desktop and start asking about Zetrix!

Features

This MCP server provides comprehensive tools for Zetrix blockchain interaction:

Account Operations

• zetrix_get_account - Get complete account information including balance and metadata
• zetrix_get_account_base - Get basic account info without assets and metadata
• zetrix_get_account_assets - Get asset holdings for an account
• zetrix_get_account_metadata - Get metadata associated with an account
• zetrix_get_balance - Get the ZETRIX balance of an account (returned in both ZETA and ZETRIX)
• zetrix_create_keypair - Generate new key pair (testing only)

Block & Ledger Operations

• zetrix_get_block - Get information about a specific block by height
• zetrix_get_latest_block - Get the latest block information
• zetrix_get_ledger - Get ledger information with optional validator/consensus details

Transaction Operations

• zetrix_get_transaction - Get transaction details by hash
• zetrix_get_transaction_history - Get completed transaction records
• zetrix_get_transaction_cache - Get pending transactions
• zetrix_get_transaction_blob - Serialize transaction data to hex format
• zetrix_submit_transaction - Submit signed transaction to blockchain
• zetrix_test_transaction - Evaluate transaction fees without submission

Contract Operations

• zetrix_call_contract - Call smart contract in sandbox environment for debugging

Utility Operations

• zetrix_check_health - Check the health status of the Zetrix node
• zetrix_multi_query - Execute multiple API queries simultaneously

WebSocket Operations (Real-time)

• zetrix_ws_connect - Connect and register to WebSocket for real-time updates
• zetrix_ws_submit_transaction - Submit transaction via WebSocket with real-time status
• zetrix_ws_subscribe_tx - Subscribe to transaction notifications for addresses
• zetrix_ws_disconnect - Disconnect from WebSocket
• zetrix_ws_status - Check WebSocket connection status

Official SDK Operations

Powered by the official zetrix-sdk-nodejs:

• zetrix_sdk_create_account - Create a new Zetrix account (address, private key, public key)
• zetrix_sdk_get_balance - Get account balance using the official SDK
• zetrix_sdk_is_activated - Check if an account is activated on the blockchain
• zetrix_sdk_get_nonce - Get account nonce for transaction sequencing
• zetrix_sdk_call_contract - Call smart contract method (query only, no state change)
• zetrix_sdk_invoke_contract - Invoke smart contract with transaction signing and submission

Cryptography Operations

Powered by the official zetrix-encryption-nodejs:

• zetrix_crypto_generate_keypair - Generate new key pair with private key, public key, and address
• zetrix_crypto_get_public_key - Derive public key from private key
• zetrix_crypto_get_address - Get Zetrix address from public key
• zetrix_crypto_validate_key - Validate private key, public key, or address format
• zetrix_crypto_sign - Sign a message with a private key
• zetrix_crypto_verify - Verify a signature against a message and public key
• zetrix_crypto_encrypt_key - Encrypt private key with password for secure storage
• zetrix_crypto_decrypt_key - Decrypt encrypted private key with password

Smart Contract Development

Comprehensive contract development support based on zetrix-contract-development-tool:

• zetrix_contract_init_dev_environment - Initialize new contract development project with templates and testing framework
• zetrix_contract_generate_advanced - Generate multi-class contracts with interfaces, libraries, utils, and comprehensive test specs
• zetrix_contract_get_chain_functions - Documentation for all Chain object functions (storage, transactions, queries)
• zetrix_contract_get_utils_functions - Documentation for all Utils object functions (math, crypto, validation)
• zetrix_contract_get_structure_guide - Guide on ES5 contract patterns, classes, and inheritance
• zetrix_contract_get_token_standard - Token standard specs (ZTP20, ZTP721, ZTP1155)
• zetrix_contract_get_testing_guide - Testing framework guide (TEST_INVOKE, TEST_QUERY)

Supported Networks

• Mainnet HTTP: https://node.zetrix.com
• Mainnet WebSocket: ws://node-ws.zetrix.com
• Testnet HTTP: https://test-node.zetrix.com
• Testnet WebSocket: ws://test-node-ws.zetrix.com

Installation

npm install
npm run build

Configuration

Option 1: Use Predefined Network

Set the network (mainnet or testnet) via environment variable:

export ZETRIX_NETWORK=mainnet  # or testnet

Option 2: Use Custom RPC URL

Specify a custom RPC URL (this overrides ZETRIX_NETWORK):

export ZETRIX_RPC_URL=https://custom-node.zetrix.com

Using .env file

Copy .env.example to .env and modify:

cp .env.example .env
# Edit .env to set ZETRIX_NETWORK or ZETRIX_RPC_URL

Usage

Development Mode

npm run dev

Production Mode

npm run build
npm start

Using with Claude Desktop

Add to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using Mainnet

{
  "mcpServers": {
    "zetrix": {
      "command": "node",
      "args": ["/absolute/path/to/zetrix-mcp-server/dist/index.js"],
      "env": {
        "ZETRIX_NETWORK": "mainnet"
      }
    }
  }
}

Using Testnet

{
  "mcpServers": {
    "zetrix": {
      "command": "node",
      "args": ["/absolute/path/to/zetrix-mcp-server/dist/index.js"],
      "env": {
        "ZETRIX_NETWORK": "testnet"
      }
    }
  }
}

Using Custom RPC URL

{
  "mcpServers": {
    "zetrix": {
      "command": "node",
      "args": ["/absolute/path/to/zetrix-mcp-server/dist/index.js"],
      "env": {
        "ZETRIX_RPC_URL": "https://custom-node.zetrix.com"
      }
    }
  }
}

API Reference

zetrix_check_health

Check the health status of the Zetrix node. The health check endpoint is /hello.

No parameters required.

Response:

{
  "healthy": true,
  "network": "mainnet",
  "rpcUrl": "https://node.zetrix.com",
  "timestamp": 1234567890
}

zetrix_get_account

Get account information for a Zetrix address.

{
  "address": "ZTX123..."
}

zetrix_get_block

Get block information by block number.

{
  "blockNumber": 12345
}

zetrix_get_latest_block

Get the latest block information (no parameters required).

zetrix_get_transaction

Get transaction details by hash.

{
  "hash": "0x123..."
}

zetrix_get_balance

Get account balance in ZTX.

{
  "address": "ZTX123..."
}

zetrix_create_keypair

Generate a new key pair (for testing purposes only).

No parameters required.

zetrix_get_account_base

Get basic account information without assets and metadata.

{
  "address": "ZTX123..."
}

zetrix_get_account_assets

Get asset holdings for an account.

{
  "address": "ZTX123...",
  "code": "USD",
  "issuer": "ZTX456..."
}

Note: code and issuer are optional but must be used together.

zetrix_get_account_metadata

Get metadata associated with an account.

{
  "address": "ZTX123...",
  "key": "metadata_key"
}

Note: key is optional.

zetrix_get_transaction_history

Get completed transaction records.

{
  "hash": "0x123...",
  "ledgerSeq": 12345
}

Note: Both parameters are optional.

zetrix_get_transaction_cache

Get pending transactions not yet executed.

{
  "hash": "0x123...",
  "limit": 10
}

Note: Both parameters are optional.

zetrix_get_ledger

Get ledger/block information with optional details.

{
  "seq": 12345,
  "withValidator": true,
  "withConsValue": true,
  "withFee": true
}

Note: All parameters are optional.

zetrix_multi_query

Execute multiple API queries simultaneously.

{
  "items": [
    {
      "method": "getAccount",
      "params": { "address": "ZTX123..." }
    },
    {
      "method": "getBlockNumber"
    }
  ]
}

zetrix_get_transaction_blob

Serialize transaction data into hexadecimal format.

{
  "transaction": {
    "source_address": "ZTX123...",
    "nonce": 1,
    "fee_limit": "1000000",
    "gas_price": "1000",
    "operations": [...]
  }
}

zetrix_submit_transaction

Submit signed transaction to blockchain for execution.

{
  "transactionBlob": "0x...",
  "signatures": [
    {
      "sign_data": "0x...",
      "public_key": "0x..."
    }
  ]
}

zetrix_call_contract

Call smart contract in sandbox environment for debugging (does not change blockchain state).

{
  "contractAddress": "ZTX123...",
  "input": "{\"method\":\"query\",\"params\":{}}",
  "sourceAddress": "ZTX456...",
  "feeLimit": "1000000",
  "gasPrice": "1000"
}

Note: All parameters are optional. Use either contractAddress (deployed contract) or code (contract source).

zetrix_test_transaction

Evaluate transaction fees without blockchain submission.

{
  "items": [
    {
      "transaction_json": {
        "source_address": "ZTX123...",
        "nonce": 1,
        "operations": [...]
      },
      "signature_number": 1
    }
  ]
}

zetrix_ws_connect

Connect and register to Zetrix WebSocket for real-time blockchain updates.

{
  "apiList": [7, 8, 16, 17, 18]
}

Note: apiList is optional. Message types: CHAIN_SUBMITTRANSACTION(7), CHAIN_SUBSCRIBE_TX(8), CHAIN_LEDGER_HEADER(16), CHAIN_TX_STATUS(17), CHAIN_TX_ENV_STORE(18)

Response:

{
  "self_addr": "node_address",
  "ledger_version": 1000,
  "monitor_version": 3000,
  "buchain_version": "3.0.0.0",
  "timestamp": 1234567890
}

zetrix_ws_submit_transaction

Submit transaction via WebSocket and receive real-time status updates.

{
  "transaction": {
    "source_address": "ZTX123...",
    "nonce": 1,
    "fee_limit": "1000000",
    "gas_price": "1000",
    "operations": [...]
  },
  "signatures": [
    {
      "public_key": "0x...",
      "sign_data": "0x..."
    }
  ]
}

Response:

{
  "status": 0,
  "tx_hash": "0x...",
  "source_address": "ZTX123...",
  "source_account_seq": 1,
  "ledger_seq": 12345,
  "new_account_seq": 2
}

Status codes: CONFIRMED(0), PENDING(1), COMPLETE(2), FAILURE(3)

zetrix_ws_subscribe_tx

Subscribe to real-time transaction notifications for specific addresses.

{
  "addresses": ["ZTX123...", "ZTX456..."]
}

After subscribing, you'll receive real-time notifications when transactions occur for these addresses.

zetrix_ws_disconnect

Disconnect from WebSocket.

No parameters required.

zetrix_ws_status

Check WebSocket connection status.

No parameters required.

Response:

{
  "connected": true,
  "wsUrl": "ws://node-ws.zetrix.com"
}

Development

Project Structure

zetrix-mcp-server/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   └── zetrix-client.ts   # Zetrix blockchain client
├── dist/                  # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Watch Mode

npm run watch

License

MIT