README.md•4.02 kB
# NIX MCP Server
A Python-based MCP (Model Context Protocol) server providing Native Indexer (NIX) query capabilities for blockchain data. This server can be used with Claude Code to enable AI-powered blockchain data queries and analysis.
## Overview
The NIX MCP Server enables querying blockchain data through the Native Indexer system using a standardized MCP interface. It communicates with a Rodeos endpoint to fetch data from various blockchains and networks.
## Features
### Available Tools
#### Configuration Tools
- `nix_get_global_configs` - Get global configurations for all or specific networks
- `nix_get_network_status` - Get the status of a specific blockchain network
#### Block Query Tools
- `nix_get_blocks` - Query blocks by range or specific height
#### Transaction Tools
- `nix_get_transaction` - Get a specific transaction by hash
- `nix_get_transactions` - Get latest transactions or filter by account
#### Account Tools
- `nix_get_account` - Get account information
- `nix_get_account_balance` - Get account balances
- `nix_get_account_keys` - Get account public keys
## Installation
### Prerequisites
- Python 3.11 or higher
- UV package manager
- Access to a Rodeos endpoint (default: http://127.0.0.1:8880)
- Optional: Access to a Nodeos endpoint for ABI fetching (default: http://127.0.0.1:8888)
### Setup
1. Clone the repository with submodules:
```bash
git clone --recursive <repository-url>
cd nix-mcp
```
2. Initialize the project (installs UV and dependencies):
```bash
./init.sh
```
3. Configure environment (optional):
```bash
cp .env.example .env
# Edit .env to set your endpoints
```
## Usage with Claude Code
### Configuration in Claude Code
1. Open Claude Code settings (⌘+, on Mac or Ctrl+, on Windows/Linux)
2. Navigate to the MCP Servers section
3. Add the NIX MCP server configuration:
```json
{
"nix-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "nix_mcp.server_fastmcp"],
"cwd": "/path/to/nix-mcp",
"env": {
"RODEOS_ENDPOINT": "http://127.0.0.1:8880",
"NODEOS_API": "http://127.0.0.1:8888",
"NIX_QUERY_CONTRACT": "nix.q",
"NIX_CONTRACT": "nix"
}
}
}
```
4. Restart Claude Code to load the MCP server
### Using the Tools in Claude
Once configured, you can use natural language to query blockchain data:
- "Get the latest blocks on NEAR mainnet"
- "Show me the transaction with hash 0x123..."
- "Get the account balance for alice.near"
- "Fetch network status for ETH testnet"
The tools will be available in Claude's tool panel and can be invoked automatically based on your queries.
## Manual Usage
### Running the Server Standalone
```bash
# Using default configuration
./run.sh
# Or with custom endpoints
RODEOS_ENDPOINT=http://your-rodeos:8880 NODEOS_API=http://your-nodeos:8888 ./run.sh
```
## Configuration
### Environment Variables
The server can be configured through environment variables (set in `.env` file or passed directly):
- `RODEOS_ENDPOINT` - Rodeos HTTP endpoint URL (default: http://127.0.0.1:8880)
- `NODEOS_API` - Nodeos API endpoint for ABI fetching (default: http://127.0.0.1:8888)
- `NIX_QUERY_CONTRACT` - NIX query contract account (default: nix.q)
- `NIX_CONTRACT` - NIX main contract account (default: nix)
- `LOG_LEVEL` - Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)
- `CLEOS_PATH` - Path to cleos binary if not in PATH (optional)
## Development
### Project Structure
```
nix-mcp/
src/
nix_mcp/
__init__.py
server.py # MCP server implementation
client.py # NIX query client
tools.py # Tool handler functions
protobuf/ # Generated protobuf files
proto/ # Source proto files
compile_proto.py # Protobuf compilation script
pyproject.toml # UV package configuration
README.md
```
## Next Steps
See NIX_MCP_IMPLEMENTATION_PLAN.md for the complete roadmap of features to be implemented.