Cast MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to cast tools from the Foundry toolkit.

Cast is a powerful command-line tool for interacting with Ethereum blockchain networks. This MCP server exposes cast's functionality as callable tools that can be used by AI models through the MCP protocol.

Features

Chain Tools

• chain: Get the symbolic name of the current chain
• chain_id: Get the chain ID of the current chain
• client: Get the current client version
• age: Get the timestamp of a block

Block Tools

• block: Get detailed information about a block
• block_number: Get the block number of a specific block or the latest block
• age: Get the timestamp of a block
• gas_price: Get the current gas price

Account Tools

• balance: Get the balance of an account in wei or ether
• nonce: Get the nonce of an account
• code: Get the bytecode of a contract (with optional disassembly)
• code_size: Get the size of contract bytecode in bytes
• storage: Get the storage value at a specific slot

Utility Tools

• max_int: Get maximum value for signed integer types (int8, int16, int32, int64, int256)
• min_int: Get minimum value for signed integer types (int8, int16, int32, int64, int256)
• max_uint: Get maximum value for unsigned integer types (uint8, uint16, uint32, uint64, uint256)
• address_zero: Get the zero Ethereum address (0x0000000000000000000000000000000000000000)
• hash_zero: Get the zero hash (0x0000000000000000000000000000000000000000000000000000000000000000)

Quick Start

Prerequisites

• Rust 1.91.0 (managed automatically via rust-toolchain.toml)
• AI client that supports MCP protocol (such as Claude Desktop, Cursor, or other MCP-compatible clients)
• Access to an Ethereum RPC endpoint (default: http://localhost:8545)

Installation

# Clone the repository
git clone <repository-url>
cd cast-mcp-server

# Build the project
make build
# Or use cargo directly
cargo build --release

# The executable will be located at:
# ./target/release/cast-mcp-server

Running

# Run in development mode
cargo run

# Run in production mode
./target/release/cast-mcp-server

Configuration

Environment Variables

The server supports the following environment variable configurations:

# Set log level (options: trace, debug, info, warn, error)
# Default: debug
RUST_LOG=info

# Note: RPC endpoints are configured per-tool via parameters
# Default RPC endpoint: http://localhost:8545

Usage Example

Configure this server in an MCP-enabled AI client:

Claude Desktop Configuration

Add to your Claude desktop configuration file:

{
  "mcpServers": {
    "cast-mcp-server": {
      "command": "/path/to/cast-mcp-server/target/release/cast-mcp-server",
      "args": []
    }
  }
}

General MCP Client Configuration

For other MCP-compatible clients, configure the server with:

• Command: Path to the compiled binary
• Arguments: None required (empty array)
• Working Directory: Project root directory

Tool Usage Examples

Here are examples of how to use the available tools:

Block Tools

{
  "name": "block",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
    "block": "latest",
    "full": true,
    "fields": ["number", "timestamp", "gasUsed"]
  }
}

{
  "name": "block_number",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
    "block": "latest"
  }
}

{
  "name": "age",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
    "block": "1000000"
  }
}

{
  "name": "gas_price",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
  }
}

Account Tools

{
  "name": "balance",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
    "who": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "ether": true
  }
}

{
  "name": "nonce",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
    "who": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "block": "latest"
  }
}

{
  "name": "code_size",
  "arguments": {
    "rpc": "https://mainnet.infura.io/v3/YOUR_PROJECT_ID",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "block": "latest"
  }
}

All tools support the following common parameters:

• rpc: Ethereum RPC endpoint URL (default: http://localhost:8545)
• block: Block identifier (number, hash, or tags like "latest", "finalized", "safe", "earliest", "pending")

Development

Code Formatting

# Format code (requires nightly toolchain)
make fmt
# Or
cargo +nightly fmt

Linting

# Run clippy linter
cargo clippy

# Run clippy with all features and stricter warnings
cargo clippy --all-targets --all-features -- -D warnings

Clean Build

make clean
# Or
cargo clean

Testing

# Run all tests
cargo test

# Run tests with verbose output
cargo test -- --nocapture

# Run specific test modules
cargo test common::account_tools
cargo test common::block_tools
cargo test common::chain_tools
cargo test common::utility_tools

# Run integration tests (if available)
cargo test --test integration_test

Contributing

Contributions are welcome! Here's how you can help:

Development Setup

1. Fork this repository
2. Clone your fork: git clone https://github.com/your-username/cast-mcp-server.git
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Make your changes
5. Format your code: make fmt
6. Test your changes: cargo test
7. Commit your changes: git commit -am 'Add amazing feature'
8. Push to the branch: git push origin feature/amazing-feature
9. Open a Pull Request

Code Standards

• Follow the existing code style (enforced by rustfmt)
• Add tests for new functionality
• Update documentation as needed
• Ensure all tests pass before submitting PR

Reporting Issues

Please include:

• Clear description of the issue
• Steps to reproduce
• Expected vs actual behavior
• Environment information (OS, Rust version, etc.)

License

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

Acknowledgments

• Foundry - Ethereum development toolkit
• MCP Specification - Model Context Protocol
• Rust - Systems programming language

Related Links

• MCP Official Documentation
• Foundry Documentation
• Cast Tool Documentation