Dune API MCP Server

This project implements a Model Context Protocol (MCP) server that exposes functionality from the Dune API, allowing LLM agents and other MCP clients to analyze blockchain information.

Features

The server provides the following MCP tools and resources based on the Dune API:

EVM Tools:

• get_evm_balances: Fetches EVM token balances for a wallet.
• get_evm_activity: Fetches EVM account activity.
• get_evm_collectibles: Fetches EVM NFT collectibles.
• get_evm_transactions: Retrieves granular EVM transaction details.
• get_evm_token_info: Fetches metadata and price for EVM tokens.
• get_evm_token_holders: Discovers EVM token holder distributions.

SVM Tools:

• get_svm_balances: Fetches SVM token balances.
• get_svm_transactions: Fetches SVM transactions (Solana only).

Resources:

• dune://evm/supported-chains: Provides a list of EVM chains supported by the Dune API.

Prompts:

• /evm_wallet_overview {walletAddress}: Get a quick overview of an EVM wallet.
• /analyze_erc20_token {chainId} {tokenAddress}: Analyze a specific ERC20 token.
• /svm_address_check {walletAddress}: Check basic information for an SVM address.

Quick Start

# Clone the repository
git clone https://github.com/crazyrabbitLTC/mcp-web3-stats.git
cd mcp-web3-stats

# Install dependencies
bun install

# Create .env file with your Dune API key
echo "DUNE_API_KEY=your_actual_dune_api_key_here" > .env

# Start the server
bun start

# In a separate terminal, run the MCP Inspector to test the tools
npx @modelcontextprotocol/inspector bun run index.ts

Installation from npm

You can install the Web3 Stats Server globally via npm:

# Install globally
npm install -g mcp-web3-stats

# Set your Dune API key as an environment variable
export DUNE_API_KEY=your_actual_dune_api_key_here

# Run the server
mcp-web3-stats

# In a separate terminal, test with the MCP Inspector
npx @modelcontextprotocol/inspector mcp-web3-stats

Alternatively, you can run it directly with npx:

# Set your Dune API key as an environment variable
export DUNE_API_KEY=your_actual_dune_api_key_here

# Run the server with npx
npx mcp-web3-stats

# In a separate terminal, test with the MCP Inspector
npx @modelcontextprotocol/inspector npx mcp-web3-stats

What You Can Do With This

This MCP server allows you and your AI assistant to analyze blockchain data and wallet information directly. Here are some example use cases:

1. Check Wallet Balances

You can quickly view all tokens (including ERC20s and NFTs) held by any wallet address:

Assistant: Let me check the balances in this wallet for you.

[Uses get_evm_balances with walletAddress=0xYourWalletAddress]

This wallet contains:
- 1.25 ETH (~$3,800)
- 500 USDC ($500)
- Several NFTs including a CryptoPunk and two Bored Apes

2. Analyze Token Information and Holders

You can research specific tokens and their distribution:

Assistant: Let me analyze this token for you.

[Uses get_evm_token_info with chainId=1 and tokenAddress=0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984]

UNI Token Information:
- Current price: $5.32
- Market cap: $2.7B 
- 24h trading volume: $89M

[Uses get_evm_token_holders with chainId=1 and tokenAddress=0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984]

Top UNI Token Holders:
1. 0x47173B170C64d16393a52e6C480b3Ad8c302ba1e: 5.2% of supply
2. 0x1a9C8182C09F50C8318d769245beA52c32BE35BC: 3.8% of supply
...

3. Review Recent Transactions

You can analyze transaction history for any address:

Assistant: Here's a summary of recent transactions.

[Uses get_evm_transactions with walletAddress=0xYourWalletAddress]

Recent activity:
- Yesterday: Swapped 2 ETH for 3,500 UNI on Uniswap
- 3 days ago: Withdrew 5 ETH from Binance
- Last week: Minted an NFT for 0.08 ETH

4. Check Solana Balances

You can also analyze Solana wallets:

Assistant: Let me check your Solana wallet balances.

[Uses get_svm_balances with walletAddress=YourSolanaAddress]

This wallet contains:
- 12.5 SOL (~$875)
- 2,500 USDC ($2,500)
- Several SPL tokens including 150 BONK

Configure this server with Claude Desktop or other MCP clients to enable your AI assistant to retrieve and analyze on-chain data in real time.

Prerequisites

• Bun (latest version recommended)
• A Dune API Key from Sim API

Setup

1. Clone the repository (if applicable) or ensure you have the project files.

2. Install dependencies:

   bun install
   

3. Configure Environment Variables: Create a .env file in the project root and add your Dune API key:

   DUNE_API_KEY=your_actual_dune_api_key_here
   

   Replace your_actual_dune_api_key_here with your valid key.

Running the Server

• To run the server directly using Bun (for development/testing):

  bun start
  

  The server will start and listen for MCP messages via stdio.

• To build the server to JavaScript (for environments that require JS): Use the configured build script which utilizes the TypeScript compiler (tsc):

  bun run build
  

  This command executes bunx tsc as defined in package.json. tsc uses the tsconfig.json file to determine entry points (like index.ts) and compilation options, outputting the JavaScript files to the ./dist directory.

  You can then run the built server with Node.js or Bun:

  node dist/index.js 
  # or
  bun dist/index.js
  

  Alternatively, if you wish to use Bun's built-in bundler directly (which may have different behavior or configuration needs than tsc), you would typically specify the entry point explicitly: bun build ./index.ts --outdir ./dist However, this project is set up to use tsc for builds via the bun run build script.

Testing with MCP Inspector

Once the server is running (e.g., via bun start in one terminal), you can connect to it using the MCP Inspector in another terminal:

# If running the TypeScript source directly
npx @modelcontextprotocol/inspector bun run index.ts

Or, if you have built the server and are running the JavaScript version:

# If running the built JavaScript version from ./dist
npx @modelcontextprotocol/inspector node dist/index.js

This will launch the Inspector UI, allowing you to discover and test the tools, resources, and prompts provided by this server.

Integrating with MCP Clients (e.g., Claude Desktop)

To use this server with an MCP client like Claude Desktop, you'll need to configure the client to launch this server. For Claude Desktop, you would modify its claude_desktop_config.json file (typically found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows).

Below are example configurations. You can choose a server name (e.g., dune_api_server or web3_stats_server) that makes sense to you.

Example 1: Running the built JavaScript version with Node.js (Recommended for stability)

This assumes you have already run bun run build to create the ./dist directory.

{
  "mcpServers": {
    "dune_api_server": { // You can name this server entry whatever you like
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/YOUR/mcp-web3-stats/dist/index.js"
      ],
      "env": {
        "DUNE_API_KEY": "your_actual_dune_api_key_here" // Replace with your key
      }
    }
  }
}

Example 2: Running the TypeScript source directly with Bun

This is convenient for development but might require specifying the full path to your Bun executable.

{
  "mcpServers": {
    "dune_api_server_dev": { // You can name this server entry whatever you like
      "command": "/full/path/to/your/bun/executable", // e.g., /Users/username/.bun/bin/bun or C:\Users\username\.bun\bin\bun.exe
      "args": [
        "run",
        "/ABSOLUTE/PATH/TO/YOUR/mcp-web3-stats/index.ts"
      ],
      "env": {
        "DUNE_API_KEY": "your_actual_dune_api_key_here" // Replace with your key
      }
    }
  }
}

Important Configuration Notes:

• API Key: You MUST replace "your_actual_dune_api_key_here" in the env block with your actual Dune API key. While the server script includes dotenv to load a local .env file, relying on the client (like Claude Desktop) to pass the environment variable via its configuration is more reliable for servers launched by external hosts.
• Absolute Paths: You MUST replace /ABSOLUTE/PATH/TO/YOUR/... with the correct and full absolute path to the dist/index.js file (for Node) or index.ts file (for Bun direct execution) and to the Bun executable if running TypeScript directly.
• Bun Executable Path: If using Bun directly (Example 2), the command might need to be the full, absolute path to your Bun executable (e.g., ~/.bun/bin/bun on macOS/Linux, or the equivalent path on Windows) if it's not universally in the PATH for applications like Claude Desktop.
• Restart Client: After saving changes to claude_desktop_config.json, you must restart Claude Desktop for the changes to take effect.