IOTA MCP Server

A comprehensive Model Context Protocol (MCP) server that provides blockchain services for IOTA and multiple EVM-compatible networks. This server enables AI agents to interact with IOTA, Shimmer, Ethereum, Optimism, Arbitrum, Base, Polygon, and many other EVM chains through a unified interface.

📋 Contents

• Overview
• Features
• IOTA Integration
• Supported Networks
• Prerequisites
• Installation
• Server Configuration
• Usage
• API Reference
  • IOTA Tools
  • IOTA Resources
  • General Tools
  • General Resources
• Security Considerations
• Project Structure
• Development
• License

🏆 IOTA APAC AngelHack 2025 Submission

This project was developed as a submission for the IOTA APAC AngelHack 2025 hackathon. It focuses on enhancing the integration between IOTA networks and AI systems through the Model Context Protocol (MCP).

Hackathon Tracks

• Primary: AI Agents
• Secondary: Developer Tools
• Additional: Cross-Chain

🔭 Overview

The IOTA MCP Server leverages the Model Context Protocol to provide blockchain services to AI agents, with a special focus on IOTA and its ecosystem. It supports a wide range of services including:

• Reading blockchain state (balances, transactions, blocks, etc.)
• Interacting with smart contracts
• Transferring tokens (native, ERC20, ERC721, ERC1155)
• IOTA-specific services (staking, network status, etc.)
• Querying token metadata and balances
• Chain-specific services across 30+ EVM networks including IOTA networks
• ENS name resolution for all address parameters (use human-readable names instead of addresses)

All services are exposed through a consistent interface of MCP tools and resources, making it easy for AI agents to discover and use blockchain functionality across multiple networks including IOTA, Shimmer, and all other EVM-compatible chains.

✨ Features

IOTA-Specific Features

• IOTA network support for IOTA EVM, IOTA Testnet, and Shimmer networks
• IOTA token information including name, symbol, decimals, and total supply
• IOTA network metrics with TPS, block time, gas usage, etc.
• IOTA network status monitoring and health checks
• IOTA balance queries for checking native token balances
• IOTA transaction analytics with gas usage, type detection, and age analysis
• IOTA smart contract analysis with function detection and standard verification
• IOTA DeFi integrations for liquidity pools, lending markets, and staking
• IOTA staking information for monitoring staking activities
• IOTA transaction history and analysis
• Cross-chain comparisons between IOTA and other networks

Blockchain Data Access

• Multi-chain support for 30+ EVM-compatible networks including IOTA
• Chain information including blockNumber, chainId, and RPCs
• Block data access by number, hash, or latest
• Transaction details and receipts with decoded logs
• Address balances for native tokens and all token standards
• ENS resolution for human-readable Ethereum addresses

Token Services

• ERC20 Tokens

  • Get token metadata (name, symbol, decimals, supply)
  • Check token balances
  • Transfer tokens between addresses
  • Approve spending allowances

• NFTs (ERC721)

  • Get collection and token metadata
  • Verify token ownership
  • Transfer NFTs between addresses
  • Retrieve token URIs and count holdings

• Multi-tokens (ERC1155)

  • Get token balances and metadata
  • Transfer tokens with quantity
  • Access token URIs

Smart Contract Interactions

• Read contract state through view/pure functions
• Write services with private key signing
• Contract verification to distinguish from EOAs
• Event logs retrieval and filtering

🌐 Supported Networks

IOTA Networks

• IOTA EVM Mainnet
• IOTA Testnet
• Shimmer

Mainnets

• Ethereum (ETH)
• Optimism (OP)
• Arbitrum (ARB)
• Arbitrum Nova
• Base
• Polygon (MATIC)
• Polygon zkEVM
• Avalanche (AVAX)
• Binance Smart Chain (BSC)
• zkSync Era
• Linea
• Celo
• Gnosis (xDai)
• Fantom (FTM)
• Filecoin (FIL)
• Moonbeam
• Moonriver
• Cronos
• Scroll
• Mantle
• Manta
• Blast
• Fraxtal
• Mode
• Metis
• Kroma
• Zora
• Aurora
• Canto
• And more...

Testnets

• Sepolia
• Optimism Sepolia
• Arbitrum Sepolia
• Base Sepolia
• Polygon Amoy
• And more...

🛠️ Prerequisites

• Bun 1.0.0 or higher
• Node.js 18.0.0 or higher (if not using Bun)

📦 Installation

Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/Danielmark001/iota_evm_mcp_server.git
cd iota_evm_mcp_server

Install Dependencies

Using Bun (recommended):

bun install

Using npm:

npm install

Environment Setup

1. Copy the example environment file:

cp .env.example .env

2. Update the .env file with your configuration:

# Server Configuration
PORT=3001
HOST=0.0.0.0
DEFAULT_CHAIN_ID=1074  # IOTA EVM Mainnet

# IOTA Configuration
IOTA_JWT_TOKEN=your_jwt_token_here
IOTA_NODE_URL=https://api.iota.org
IOTA_MNEMONIC=your_mnemonic_here  # Required for sending transactions

# SSL Configuration (optional for development)
SSL_CERT_PATH=./certs/client.crt
SSL_KEY_PATH=./certs/client.key
SSL_CA_PATH=./certs/iota-root-ca.crt

⚙️ Configuration

The server uses the following default configuration that can be adjusted in the .env file:

# Create a .env file in the root directory
touch .env

# Add configuration values
echo "PORT=3001" >> .env
echo "HOST=0.0.0.0" >> .env
echo "DEFAULT_CHAIN_ID=1074" >> .env  # IOTA EVM Mainnet

🚀 Usage

Start the Server

Using stdio (for embedding in CLI tools)

# Start the server
bun start

# Development mode with auto-reload
bun dev

Using HTTP Server (for web applications)

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

Build for Production

# Build the project
bun run build

# Build the HTTP server
bun run build:http

Docker Deployment

# Build the Docker image
docker build -t iota_evm_mcp_server .

# Run the container
docker run -p 3001:3001 iota_evm_mcp_server

🔌 Integrating with AI Systems

Example: Using with Claude, GPT-4, or other AI assistants

AI platforms that support the Model Context Protocol can directly connect to the IOTA MCP Server. For example, with a properly configured MCP-enabled AI:

User: "Check the balance of address 0x1234... on the IOTA network"

AI Assistant: [Uses IOTA MCP Server to check balance and returns]
"The balance of address 0x1234... on the IOTA network is 15.75 MIOTA"

Example: Using the server with custom AI agents

// Connect to MCP server
const mcpClient = new McpClient({
  endpoint: "http://localhost:3001",
});

// Call IOTA-specific tool
const response = await mcpClient.callTool("get_iota_balance", {
  address: "0x1234...",
  network: "iota",
});

console.log(response);

📚 API Reference

The server provides a comprehensive set of tools and resources for interacting with IOTA and other blockchain networks. For detailed API documentation, please see the API Reference.

Key IOTA Tools

• get_iota_network_info: Get information about IOTA networks
• get_iota_balance: Get token balances for an address
• transfer_iota: Transfer IOTA tokens to another address
• get_iota_staking_info: Get staking information
• verify_iota_network_status: Check network health and status

Key IOTA Resources

• iota://{network}/info: Information about an IOTA network
• iota://{network}/block/latest: Latest block on an IOTA network
• iota://{network}/address/{address}/balance: Token balance for an address
• iota://{network}/status: Network health and status

🧪 Testing

Run the test suite:

# Using Bun (recommended)
bun test

# Using npm
npm test

Run specific test files:

bun test test/iota-defi-agent.test.ts

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and follow our code of conduct.

🐛 Troubleshooting

Common Issues

1. Node Version Error

   • Make sure you have Node.js 18.0.0 or higher installed
   • Use nvm to manage Node.js versions

2. Bun Installation Issues

   • Follow the official Bun installation guide
   • Try reinstalling Bun if you encounter issues

3. IOTA Connection Issues

   • Verify your IOTA node URL is correct
   • Check your JWT token is valid
   • Ensure your network connection is stable

4. Build Errors

   • Run bun install to ensure all dependencies are installed
   • Clear the build directory: rm -rf build/
   • Check TypeScript configuration in tsconfig.json

Getting Help

• Open an issue on GitHub
• Check our FAQ

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• IOTA Foundation for their amazing technology
• Model Context Protocol for enabling AI-blockchain interaction
• Viem for the EVM interaction library
• IOTA APAC AngelHack 2025 organizers and mentors
• All contributors and supporters

Built with ❤️ for the IOTA community