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