Dune API MCP Server

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

Installation from npm

You can install the Web3 Stats Server globally via npm:

Alternatively, you can run it directly with npx:

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:

2. Analyze Token Information and Holders

You can research specific tokens and their distribution:

3. Review Recent Transactions

You can analyze transaction history for any address:

4. Check Solana Balances

You can also analyze Solana wallets:

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:

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

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.

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.

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.