NIX MCP Server - Simplified Version

A simplified MCP (Model Context Protocol) server for querying NIX blockchain data using JSON and ABI, without protobuf dependencies.

Features

Simple JSON-based queries - No protobuf compilation required
Dynamic ABI discovery - Automatically fetches available queries from contracts
Automatic ABI caching - Caches ABIs from cdev environment on startup
Environment switching - Query different environments (dev, uat, prod, etc.)
JSON file support - Pass query parameters via JSON files
Three core tools:
- list_queries - List all available queries from contract ABI
- get_query_abi - Get query structure with JSON examples
- query - Execute queries with JSON parameters

Prerequisites

Python 3.11+
cleos command-line tool (for blockchain queries)
Access to Rodeos and Nodeos endpoints

Quick Start

1. Clone and Initialize

# Clone the repository git clone <repository-url> cd nix-mcp # Run initialization script (installs uv and dependencies) ./init.sh # Or manually with uv curl -LsSf https://astral.sh/uv/install.sh | sh uv sync

2. Configure

# Copy environment template cp .env.example .env # Edit .env with your endpoints: # RODEOS_API=http://your-rodeos-endpoint:8880 # NODEOS_API=http://your-nodeos-endpoint:8888

3. Run the Server

# Using make make run # Or directly uv run python main.py # Or with the run script ./run.sh

Available Tools

1. List Queries

Lists all available query actions from the contract ABI.

{ "tool": "list_queries", "params": { "contract": "nix.q", "filter_pattern": "global", "environment": "dev" } }

2. Get Query ABI

Returns the structure and JSON template for a specific query.

{ "tool": "get_query_abi", "params": { "query_name": "globalconfn", "contract": "nix.q", "include_example": true, "environment": "dev" } }

3. Execute Query

Executes a NIX query with JSON parameters.

{ "tool": "query", "params": { "action": "globalconfn", "params": { "blockchain": "ETH", "network": "testnet" }, "contract": "nix.q", "environment": "dev" } }

Environment Support

The MCP server now supports dynamic environment switching without restarting. You can specify the target environment for each query:

Available Environments

dev - Development environment (default)
uat - User Acceptance Testing
cdev - Custody Development
perf - Performance testing
perf2 - Secondary performance testing
simnext - Simulation/Next environment
prod - Production environment
local - Local development
snapshot - Snapshot environment

Example: Query Different Environments

# Query SOL mainnet configuration from production result = await client.query( contract="nix.q", action="globalconfn", params={ "blockchain": "SOL", "network": "mainnet" }, environment="prod" # Specify production environment ) # List queries available in UAT queries = await list_queries( contract="nix.q", environment="uat" )

Usage Examples

Python Client

from nix_mcp import SimpleNixClient import asyncio async def example(): # Create client for specific environment client = SimpleNixClient(environment="prod") # Query all global configs result = await client.query( contract="nix.q", action="globalconfs", params={} ) print(result) # Query specific network result = await client.query( contract="nix.q", action="globalconfn", params={ "blockchain": "ETH", "network": "testnet" } ) print(result) # Create client for different environment dev_client = SimpleNixClient(environment="dev") dev_result = await dev_client.query( contract="nix.q", action="globalconfs", params={} ) print(f"Dev environment result: {dev_result}") asyncio.run(example())

Discover Available Queries

from nix_mcp import ABIFetcher fetcher = ABIFetcher() actions = fetcher.get_actions("nix.q") print(f"Available queries: {actions}")

Testing

# Run basic tests uv run python test_simple.py # Test environment switching uv run python test_env_switching.py # Test the complete expected flow uv run python test_expected_flow.py

Claude Desktop Integration

Add to your Claude Desktop configuration:

{ "mcpServers": { "nix-mcp": { "command": "uv", "args": ["run", "python", "/full/path/to/nix-mcp/main.py"] } } }

Project Structure

nix-mcp/ ├── src/nix_mcp/ │ ├── simple_client.py # Core client using cleos │ ├── abi_fetcher.py # ABI fetching and parsing │ ├── tools.py # MCP tool handlers │ ├── server_fastmcp.py # FastMCP server │ └── json_templates.py # Query templates ├── main.py # Entry point ├── test_simple.py # Test script ├── .env.example # Environment template └── README.md # This file

Environment Variables

NODEOS_ENV - Default environment to use when not specified (dev, uat, cdev, prod, etc.)
RODEOS_API - Override Rodeos endpoint for all environments
NODEOS_API - Override Nodeos endpoint for all environments
CLEOS_PATH - Path to cleos binary (optional if in PATH)

You can also set environment-specific overrides:

RODEOS_API_DEV, RODEOS_API_UAT, RODEOS_API_PROD, etc.
NODEOS_API_DEV, NODEOS_API_UAT, NODEOS_API_PROD, etc.

Transaction Query Example

Here's a complete example of querying a raw transaction as described in the expected flow:

Step 1: Find the appropriate query

# List all available queries result = await list_queries( contract="nix.q", filter_pattern="raw", # Filter for transaction-related queries environment="cdev" ) # This will show queries like: rawtrxspb, rawtransaction, etc.

Step 2: Get the query ABI structure

# Get the ABI for rawtrxspb query result = await get_query_abi( query_name="rawtrxspb", contract="nix.q", environment="cdev" ) # Shows the expected input structure

Step 3: Execute the query

# Query for ETH mainnet transaction in cdev result = await query( action="rawtrxspb", params={ "network": { "blockchain": "ETH", "network": "mainnet" }, "transaction_identifier": { "hash": "0abe152ba84b35026451d68a55310ec58450a167a82a55fae2ff691ebc7236bf" } }, contract="nix.q", environment="cdev" )

Or using a JSON file:

# Using pre-built JSON file result = await query( action="rawtrxspb", params="examples/raw_transaction_query.json", contract="nix.q", environment="cdev" )

The actual cleos command executed:

cleos -u $RODEOS_API push action --use-old-send-rpc --return-failure-trace 0 nix.q rawtrxspb '{"network":{"blockchain":"ETH","network":"mainnet"},"transaction_identifier":{"hash":"0abe152ba84b35026451d68a55310ec58450a167a82a55fae2ff691ebc7236bf"}}' -sj

Common Query Templates

Example JSON files in examples/ directory:

raw_transaction_query.json - Query raw transaction details
global_config_query.json - Query global configuration for a network
network_status_query.json - Query network status

Additional query types:

Global configurations (globalconfs, globalconfn)
Network status (nwstatus)
Account queries (accounts, balances)
Block queries (blocks)
Transaction queries (transaction, transactions, rawtrxspb)

Troubleshooting

cleos not found

Ensure cleos is installed and in your PATH, or set CLEOS_PATH in .env

Connection errors

Verify your RODEOS_API and NODEOS_API endpoints are accessible

Import errors

Run uv sync to ensure all dependencies are installed

License

[Your License]

NIX MCP Server