Provides examples for testing the MCP server using cURL, supporting API documentation and HTTP requests
Includes API examples in Node.js for interacting with the Zilliqa blockchain
Enables persistent local setup with process management capabilities including auto-restart on crashes, system startup integration, and log management
Includes API examples in Python for interacting with the Zilliqa blockchain
Supports deployment to Railway cloud platform with automatic configuration via railway.toml
Supports deployment to Render cloud platform with automatic configuration via render.yaml
Zilliqa MCP Server
A comprehensive Model Context Protocol (MCP) server that provides access to Zilliqa blockchain documentation, API examples, address conversion tools, faucet integration, live network statistics, and automatic content fetching from source URLs.
Understanding Server Modes
This MCP server can run in two modes:
- HTTP Mode (Default) - For web access, API calls, and cloud deployment
- Accessible via
http://localhost:PORT
- Can be deployed to Render, Railway, etc.
- Supports CORS for cross-origin requests
- Cannot be used with Claude Desktop
- Accessible via
- STDIO Mode - For Claude Desktop integration only
- Communicates through standard input/output
- Required for Claude Desktop
- Cannot be accessed via HTTP
- Set with
MCP_TRANSPORT=stdio
⚠️ Important: These modes are mutually exclusive. A server running in HTTP mode cannot communicate with Claude Desktop, and vice versa.
Quick Start
1. Installation
2. Run the Server
The server will run in HTTP mode by default and be available at http://localhost:3000
(or your specified port).
⚠️ Warning: Running npm start
will NOT make the server available to Claude Desktop. For Claude Desktop integration, see the Claude Desktop Integration section below.
3. Test the Server
Features
Documentation & API Access
- search_zilliqa_docs - Search through Zilliqa documentation for specific topics
- get_zilliqa_api_example - Get specific API examples by name and programming language
- list_zilliqa_apis - List all available API methods in the documentation
- get_zilliqa_network_info - Get network information (RPC URLs, chain IDs, explorers, faucets)
Address Conversion Tools
- convert_zilliqa_address - Convert between bech32 (zil1...) and hex address formats
- validate_zilliqa_address - Validate Zilliqa address format without conversion
- batch_convert_zilliqa_addresses - Convert multiple addresses at once (up to 100 addresses)
Faucet Integration
- request_zilliqa_faucet - Request test ZIL tokens from devnet/testnet faucets (100 ZIL per request)
Network Statistics
- get_network_stats - Get live network statistics for mainnet, testnet, and devnet
- Latest block information (number, timestamp, gas usage)
- Network status and configuration
- Real-time blockchain metrics
Staking Portal Information
- get_staking_portal_info - Get comprehensive information about Zilliqa 2.0 staking portal (stake.zilliqa.com)
- Overview of staking portal features and functionality
- Liquid staking vs non-liquid staking options
- Validator selection guidance and considerations
- Step-by-step staking instructions
- Staking requirements and minimum amounts
- Rewards information and claiming process
Smart Content Fetching
- Universal Source URL Fetching - Automatically fetches and includes live content from any source URLs mentioned in documentation
- Enhanced Content Extraction - Intelligently extracts main content from various website structures
- Real-time Documentation - Always provides up-to-date information by fetching from original sources
Production Deployment
This server is designed for easy deployment to cloud platforms:
Deploy to Render (Recommended)
- Push your code to GitHub
- Connect your repository to Render
- The included
render.yaml
will automatically configure:- HTTP mode with environment variables
- Node.js runtime
- Build and start commands
- Your MCP server will be available at
https://your-app.onrender.com
Deploy to Railway
- Push your code to GitHub
- Connect your repository to Railway
- The included
railway.toml
handles configuration - Get your public URL from Railway dashboard
Environment Variables
For production deployment, you can set:
The server runs in HTTP mode by default. No need to set MCP_TRANSPORT
unless you want STDIO mode.
Alternative: Claude Desktop Integration
⚠️ Important: Claude Desktop only supports STDIO mode, not HTTP. If you want to use this MCP server with Claude Desktop, you must configure it for STDIO mode:
Replace /path/to/zilliqa-experimental
with the actual path where you cloned the repository.
⚠️ Common Mistake: Without "MCP_TRANSPORT": "stdio"
in the config, the server will start in HTTP mode and Claude Desktop will fail to connect. You'll see the server running but Claude won't be able to use it.
Configuration File Location
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
Usage Examples
After installation and configuration, you can use these tools in Claude:
Documentation & API Examples
- "Search Zilliqa docs for GetBalance"
- "Get API example for GetTransaction in Python"
- "List all available Zilliqa APIs"
- "Get devnet network information"
Address Conversion
- "Convert this address to hex: zil1abc123..."
- "Validate this Zilliqa address: 0x123abc..."
- "Convert these addresses in batch: [zil1abc..., 0x123...]"
Faucet Requests
- "Request devnet tokens for zil1abc123..."
- "Get testnet ZIL for my address"
Network Statistics
- "Get mainnet network statistics"
- "Show testnet network stats"
- "Get devnet blockchain metrics"
Staking Portal Information
- "Get staking portal overview"
- "Tell me about liquid staking options"
- "How do I stake on Zilliqa 2.0?"
- "What are the staking requirements?"
- "Explain validator selection process"
- "How do I claim staking rewards?"
Smart Features
- All responses automatically include live content from source URLs
- Documentation is always up-to-date with latest information
- Addresses are automatically formatted in code blocks for easy copying
Technical Details
Supported Networks
- Devnet - Development network with latest features (Chain ID: 33103)
- Testnet - Stable testing environment (Chain ID: 33101)
- Mainnet - Production network (Chain ID: 32769)
Address Formats
- Bech32 - Human-readable format (zil1...) - recommended for user interfaces
- Hex - Machine-readable format (40 characters, with/without 0x prefix)
- Validation - Comprehensive format checking with detailed error messages
API Documentation
The server includes comprehensive Zilliqa API documentation with examples in:
- Java
- Python
- Go
- Node.js
- cURL
Access patterns include blockchain APIs, transaction handling, and smart contract interactions.
Smart Content Features
- Universal URL Detection - Automatically detects any HTTP/HTTPS URL in documentation
- Content Extraction - Intelligently extracts main content from various website structures
- Fallback Mechanisms - Graceful handling when content cannot be fetched
- Live Documentation - Always provides current information from original sources
Network Statistics Sample Output
Persistent Local Setup with PM2
For a persistent local server that auto-restarts and survives system reboots, you can use PM2:
Installing PM2
Starting with PM2
PM2 Management Commands
Why Use PM2?
- Auto-restart on crashes
- Persistent across terminal sessions
- System startup integration
- Log management with rotation
- Process monitoring built-in
Note: PM2 is optional. For development, running directly with npm start
is fine. For production deployment to Render/Railway, PM2 is not needed as these platforms handle process management.
Development
Running in Development Mode
Making HTTP Requests
Example requests to test your server:
Testing
Project Structure
Security Considerations for Public Deployment
When deploying publicly, consider adding:
- Authentication (API keys or OAuth)
- Rate limiting to prevent abuse
- Request logging for monitoring
- CORS configuration for specific domains
- Input validation (already included)
Troubleshooting
Claude Desktop Can't Find the MCP Server
If Claude Desktop shows the Zilliqa tools are unavailable:
- Check your config has STDIO mode enabled:
- Verify the server starts in STDIO mode:
- Check Claude Desktop logs:
Server Runs but Claude Can't Use It
This usually means the server is running in HTTP mode instead of STDIO:
- ❌ Output: "Zilliqa MCP Server running on HTTP port 3000"
- ✅ Output: "Zilliqa MCP Server running on stdio"
Can't Access HTTP Server from Browser
If you're trying to access the HTTP server:
- Make sure you're NOT using
MCP_TRANSPORT=stdio
- Default URL is
http://localhost:3000
(not HTTPS) - Check if another process is using the port
License
MIT
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Provides access to Zilliqa blockchain documentation and API examples through search capabilities and examples in multiple programming languages.
Related MCP Servers
- AsecurityAlicenseAqualityFacilitates searching and accessing programming resources across platforms like Stack Overflow, MDN, GitHub, npm, and PyPI, aiding LLMs in finding code examples and documentation.Last updated -638JavaScriptAGPL 3.0
- -securityAlicense-qualityEnables interaction with GitHub repositories through the GitHub API, allowing file operations, repository management, issue tracking, and code search through natural language commands.Last updated -72TypeScriptMIT License
- -securityFlicense-qualityA Solana blockchain interaction server that allows AI tools to query blockchain data using natural language, access structured token information, and generate human-readable explanations of complex blockchain concepts.Last updated -9Python
- -securityFlicense-qualityEnables AI assistants to search documentation of packages and services to find implementation details, examples, and specifications.Last updated -Python