Dune API
STDIOMCP server for blockchain data analysis using Dune API for wallet and token insights.
MCP server for blockchain data analysis using Dune API for wallet and token insights.
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.
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.# 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
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
This MCP server allows you and your AI assistant to analyze blockchain data and wallet information directly. Here are some example use cases:
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
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
...
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
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.
Clone the repository (if applicable) or ensure you have the project files.
Install dependencies:
bun install
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.
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.
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.
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:
"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/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.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.claude_desktop_config.json, you must restart Claude Desktop for the changes to take effect.