Zilliqa MCP Server

Model Context Protocol (MCP) server providing access to Zilliqa developer documentation, network information, and faucet functionality.

Features

• 📚 Documentation Search: Search across 283+ code snippets from official Zilliqa documentation
• 🌐 Network Information: Get details for Zilliqa mainnet, testnet, and devnet
• 💧 Faucet Requests: Request testnet/devnet tokens programmatically
• 📊 Live Validator Metrics: Real-time validator performance and reward data from Grafana
• ⚡ Smart Caching: In-memory caching (24h for docs, 5min for metrics) for fast responses

Installation

Using npx (Recommended)

npx -y zilliqa-mcp

Install Globally

npm install -g zilliqa-mcp
zilliqa-mcp

Configuration

Basic Setup

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "zilliqa-docs": {
      "command": "npx",
      "args": ["-y", "zilliqa-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "zilliqa-docs": {
      "command": "npx",
      "args": ["-y", "zilliqa-mcp"]
    }
  }
}

Important: Restart Cursor/Claude Desktop after configuration changes.

Cache Duration (Optional)

By default, documentation is cached for 24 hours. Customize using the ZILLIQA_MCP_CACHE_TTL environment variable:

{
  "mcpServers": {
    "zilliqa-docs": {
      "command": "npx",
      "args": ["-y", "zilliqa-mcp"],
      "env": {
        "ZILLIQA_MCP_CACHE_TTL": "12h"
      }
    }
  }
}

Supported formats:

• "30m" - 30 minutes
• "1h" - 1 hour
• "6h" - 6 hours
• "12h" - 12 hours
• "24h" - 24 hours (default)
• "7d" - 7 days (maximum)
• Raw milliseconds: "3600000" (1 hour)

Limits: Minimum 5 minutes, maximum 7 days

Available Tools

1. search_dev_docs

Search Zilliqa developer documentation with fuzzy matching and relevance scoring.

Parameters:

• query (string, required): Search query
• fetch_full (boolean, optional): Fetch full GitHub content for snippets (default: false)

Example:

Search for "staking rewards"
Search for "contract deployment" with full GitHub content

2. get_network_info

Get information about Zilliqa networks including RPC endpoints, chain IDs, and block explorers.

Parameters:

• network (string, optional): Network name (mainnet, testnet, or devnet). Returns all if not specified.

Example:

Get testnet network info
Show all Zilliqa networks

3. request_faucet_tokens

Request test tokens from Zilliqa testnet or devnet faucet.

Parameters:

• network (string, required): Network name (testnet or devnet)
• address (string, required): Wallet address (0x...)

Example:

Request faucet tokens for 0x1234... on devnet

4. get_validator_rewards

Get live validator performance data from the Zilliqa ZQ2 network showing hourly reward rates.

Parameters:

• limit (number, optional): Number of top validators to return (default: 10, max: 50)

Example:

Get top 20 validators by rewards
Show current validator rewards

Features:

• Real-time data from Grafana public dashboard
• 26+ active validators tracked
• Cached for 5 minutes
• Includes validator names and addresses

5. get_dashboard_info

Get information about the Zilliqa ZQ2 validator dashboard including available metrics panels.

Example:

Show dashboard info
What metrics are available?

Documentation Sources

The MCP server loads documentation from 7 official Zilliqa sources:

1. Delegated Staking (54 snippets)
2. Zilliqa 2.0 Developer Docs (78 snippets)
3. Developer Portal (53 snippets)
4. Zilliqa Developer Resources (89 snippets)
5. ZQ2 Core Documentation (1 snippet)
6. ETH Network Stats API (2 snippets)
7. ETH Metrics Exporter (6 snippets)

Total: 283 documentation snippets

Performance

• First search: 5-10 seconds (loads 283 snippets into cache)
• Subsequent searches: <100ms (served from in-memory cache)
• Cache duration: 24 hours (configurable via environment variable)
• Memory usage: ~1-2MB for cached snippets

Troubleshooting

"No snippets loaded" Error

Solution: The server caches documentation on first use. If you see this error:

1. Wait for the first search to complete (may take 5-10 seconds)
2. Check network connectivity to context7.com
3. Restart your MCP client (Cursor/Claude Desktop)

Slow First Search

Expected Behavior: The first search loads 283 snippets from 7 sources, taking 5-10 seconds. All subsequent searches are instant due to caching.

Cache Not Working

Restart the MCP server to reload the cache. In Cursor/Claude Desktop, restart the entire application.

Data Sources

Documentation

The MCP server aggregates 283+ code snippets from 7 official Zilliqa sources (see above).

Live Metrics

Real-time validator and network metrics from the Zilliqa Insights Dashboard:

• Hourly validator rewards
• Total network rewards (proposer + cosigner)
• Reward distribution across validators
• Validator performance ratios

Metrics are refreshed every 5 minutes and include 26+ active validators from major providers (Binance, Moonlet, Luganodes, Stakefish, etc.).

Version

Current: v1.3.0

Latest Features (v1.3.0)

• ✅ Live validator rewards from Grafana dashboard
• ✅ Real-time network metrics integration
• ✅ 26+ validator tracking with name resolution
• ✅ Separate cache TTLs (24h docs, 5min metrics)

Previous Features

• ✅ In-memory caching with configurable TTL
• ✅ Context7 documentation format support
• ✅ 283 snippets from 7 official Zilliqa sources
• ✅ Fuzzy search with relevance scoring
• ✅ 100x faster searches after initial cache load
• ✅ Human-readable cache duration formats ("30m", "6h", "24h", etc.)

License

MIT

Built with the Model Context Protocol by Anthropic