ccbbccbb/viemcp
If you are the rightful owner of viemcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server that provides blockchain interaction capabilities through viem, enabling AI assistants to read onchain data, interact with smart contracts, and prepare transactions across multiple EVM chains.
A Model Context Protocol (MCP) server that provides blockchain interaction capabilities through viem and wagmi, enabling AI assistants to help with integration of both frameworks as well as read onchain data & view smart contract state.
Features
- Multi-chain Support: Access EVM chains via viem; minimal defaults with dynamic chain resolution
- Read Operations: Query balances, blocks, transactions, logs, storage, and smart contract state
- Token Standards: ERC20 read operations (balance, metadata, allowance)
- ENS: Resolve ENS names, reverse lookups, and fetch resolvers
- Tx Prep & Encoding: Prepare transaction requests; encode function and deploy data
- Embedded Patterns: Instant access to viem/wagmi code patterns (offline, zero-latency)
- Wagmi Support: React hooks patterns and code generation for Web3 UIs
- Docs Resources: Live viem docs from GitHub + embedded pattern library
- Type Safety: TypeScript throughout with viem's type inference
- Centralized types in
src/core/types.ts
for tool outputs and parameters
- Centralized types in
- Security-First: Read-only; prepares unsigned transactions only (no key management)
Installation
# Install dependencies
bun install
# Build the server
bun run build
# Start the server
bun run start
Deployment
See DEPLOYMENT.md
for publishing to npm and deploying the site/
app to Vercel, including required secrets and example GitHub Actions workflows. Example environment variables are in env.example
.
Configuration
Environment Variables
Create a .env
file in the project root. RPC URLs can be provided per-chain and per-provider. As of v0.0.5, the server includes default public RPC URLs for common chains as fallbacks.
# RPC provider selector (optional; default: drpc)
RPC_PROVIDER=drpc
# RPC endpoints (optional - defaults available for major chains)
# Generic naming (preferred):
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/KEY
MAINNET_RPC_URL=https://eth.llamarpc.com
# Provider-specific naming (takes precedence if RPC_PROVIDER matches):
ETHEREUM_RPC_URL_DRPC=https://lb.drpc.org/ogrpc?network=ethereum&dkey=KEY
MAINNET_RPC_URL_DRPC=https://lb.drpc.org/ogrpc?network=ethereum&dkey=KEY
# Dynamic docs branch for resources (optional; default: main)
VIEM_DOCS_BRANCH=main
# Enable/disable dynamic chain resolution from viem (optional; default: enabled)
VIEM_ENABLE_DYNAMIC_CHAIN_RESOLUTION=true
# Register custom chains (optional). JSON array of viem Chain objects
VIEM_CUSTOM_CHAINS=[
{ "id": 8453, "name": "Base", "nativeCurrency": {"name":"Ether","symbol":"ETH","decimals":18}, "rpcUrls": {"default": {"http": ["https://mainnet.base.org"]}} }
]
Default Chain Support (v0.0.5+)
The server includes default public RPC URLs for these chains (no configuration needed):
- Ethereum/Mainnet (
mainnet
,ethereum
,eth
) - Polygon
- Arbitrum
- Optimism
- Base
- Avalanche
- BSC (Binance Smart Chain)
- Gnosis
- Fantom
- Celo
- Moonbeam
- Aurora
Custom RPC URLs in environment variables always take precedence over defaults.
MCP Client Configuration
Add to your MCP client settings (e.g., Claude Desktop):
{
"mcpServers": {
"viemcp": {
"command": "node",
"args": ["/absolute/path/to/viemcp/build/index.js"],
"env": {
"ETHEREUM_RPC_URL": "https://eth.llamarpc.com"
}
}
}
}
Available Tools
The server provides 17 tools, all with the viem
prefix. Tools have been consolidated to reduce complexity while maintaining comprehensive blockchain interaction capabilities.
Consolidated Tools (12 tools)
- viemBlockInfo ā Block header plus optional tx count/full txs
args: { numberOrTag?: string, includeTxCount?: boolean, includeFullTransactions?: boolean, chain?: string }
- viemTransactionInfo ā Transaction plus optional receipt/logs
args: { hash: string, includeReceipt?: boolean, includeLogs?: boolean, chain?: string }
- viemAccountInfo ā Account balance and optional nonce
args: { address: string, blockTag?: string, historicalBalanceAt?: string, includeNonce?: boolean, chain?: string }
- viemGasInfo ā Gas price and/or fee history
args: { includePrice?: boolean, history?: { blockCount?: string, newestBlock?: string, rewardPercentiles?: number[] }, chain?: string }
- viemEnsInfo ā Resolve ENS data for name/address (address, name, resolver, avatar, text records)
args: { lookupType: "name" | "address", value: string, includeAddress?: boolean, includeName?: boolean, includeResolver?: boolean, includeAvatar?: boolean, textKeys?: string[], chain?: string }
- viemErc20Info ā Combined ERC20 metadata/balance/allowance
args: { token: string, owner?: string, spender?: string, includeMetadata?: boolean, includeBalance?: boolean, includeAllowance?: boolean, chain?: string }
- viemContractState ā Get contract code and/or storage slots
args: { address: string, slots?: string[], blockTag?: string, includeCode?: boolean, includeStorage?: boolean, chain?: string }
- viemEncodeData ā Encode function/deploy data
args: { mode: "function" | "deploy", abi: unknown[], functionName?: string, args?: unknown[], bytecode?: string, constructorArgs?: unknown[] }
- viemContractAction ā Read/simulate/estimateGas for a function
args: { action: "read" | "simulate" | "estimateGas", address: string, abi: unknown[], functionName: string, args?: unknown[], account?: string, value?: string, blockTag?: string, chain?: string }
- viemTransactionBuild ā Estimate gas or prepare tx
args: { mode: "estimateGas" | "prepare", from?: string, to?: string, data?: string, value?: string, gas?: string, maxFeePerGas?: string, maxPriorityFeePerGas?: string, gasPrice?: string, nonce?: string, chain?: string }
- viemChainInfo ā Chain id and optionally supported chains/RPC URL
args: { includeSupported?: boolean, includeRpcUrl?: boolean, chain?: string }
- viemGetLogs ā Filter logs by address/topics and range
args: { address?: string, topics?: unknown[], fromBlock?: string, toBlock?: string, chain?: string }
Utility Tools (5 tools)
- viemParseEther ā Convert ETH to wei
args: { value: string }
- viemFormatEther ā Convert wei to ETH
args: { value: string }
- viemMulticall ā Batch multiple contract reads
args: { contracts: { address: string, abi: unknown[], functionName: string, args?: unknown[] }[], allowFailure?: boolean, chain?: string }
- viemIsAddress ā Validate Ethereum address
args: { address: string }
- viemKeccak256 ā Hash data with Keccak256
args: { data: string }
Available Resources
In addition to tools, this server exposes live documentation resources for viem. These are fetched directly from GitHub and exposed under the viem://docs/*
URI scheme.
Documentation Resources
Viem Documentation (GitHub-based)
viem://docs/github-index
ā Lists all available viem docs pagesviem://docs/github/{path}.mdx
ā Raw content of a specific viem docs page
Embedded Pattern Library (Offline, Zero-latency)
viem://patterns
ā Common viem code patternswagmi://patterns
ā Wagmi React hooks patternsweb3://common-patterns
ā Common Web3 development patternspatterns://search?q=QUERY
ā Search all patternswagmi://docs/getting-started
ā Wagmi documentation links
Available Prompts
Prompts are higher-level assistants bundled with the server:
Code Generation
-
generate_viem_code
- Args:
feature
(string),hints
(optional string) - Behavior: Generates viem code consulting docs resources
- Attached resource:
viem://docs/github-index
- Args:
-
generate_wagmi_code
(New in v0.0.5)- Args:
feature
(string),hints
(optional string) - Behavior: Generates React components with wagmi hooks
- Uses: Embedded wagmi patterns for instant reference
- Args:
-
viem_wagmi_pattern
(New in v0.0.5)- Args:
pattern
(string),category
(optional: 'viem'|'wagmi'|'common') - Behavior: Retrieves specific pattern with explanation
- Uses: Embedded pattern library
- Args:
Analysis
-
analyze_transaction
- Args:
txHash
(string),chain
(optional; defaults toethereum
) - Behavior: Human-style transaction analysis
- Args:
-
analyze_address
- Args:
address
(string),chain
(optional; defaults toethereum
) - Behavior: Human-style address analysis
- Args:
-
search_viem_docs
- Args:
query
(string) - Behavior: Searches viem docs and summarizes findings
- Attached resource:
viem://docs/github-index
- Args:
Usage Examples
Get ETH Balance
// Resolve ENS via consolidated tool then fetch balance
const { address } = await callTool("viemEnsInfo", { lookupType: "name", value: "vitalik.eth", includeAddress: true, includeAvatar: true, textKeys: ["com.twitter"] })
.then(r => JSON.parse(r.content[0].text));
await callTool("viemAccountInfo", { address, chain: "ethereum" });
Read Smart Contract
await callTool("viemContractAction", {
action: "read",
address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
abi: [...], // ERC20 ABI
functionName: "balanceOf",
args: ["0x..."],
chain: "ethereum"
});
Prepare Transaction Request
await callTool("viemTransactionBuild", {
mode: "prepare",
to: "0x...",
value: "1000000000000000000", // 1 ETH in wei
chain: "ethereum"
});
Docs Resources Index
await getResource("viem://docs/github-index");
Supported Chains
The server ships with a minimal default set (Ethereum mainnet aliases: mainnet
, ethereum
, eth
) to keep footprint small. It can:
- Load custom RPC URLs from environment (see Configuration)
- Dynamically resolve chains by ID from
viem
ifVIEM_ENABLE_DYNAMIC_CHAIN_RESOLUTION
is not set tofalse
- Register additional custom chains via
VIEM_CUSTOM_CHAINS
List what is currently available at runtime with:
await callTool("viemChainInfo", { includeSupported: true });
Security Considerations
- No Private Keys: This server never handles private keys
- Read-Only: Focuses on reading blockchain state
- Transaction Preparation: Only prepares unsigned transactions
- Input Validation: All inputs are validated before processing
Development
# Install dependencies
bun install
# Run in development mode
bun run dev
# Type-check
bun run typecheck
# Lint code
bun run lint
# Format code
bun run format
Architecture
viemcp/
āāā src/
ā āāā index.ts # Entry point & tool registrations
ā āāā core/
ā āāā chains.ts # Chain registry & RPC resolution
ā āāā clientManager.ts # Viem client lifecycle & cache
ā āāā prompts.ts # Prompt registrations
ā āāā resources/
ā ā āāā docs.ts # GitHub-backed viem docs resources
ā āāā responses.ts # Response helpers
ā āāā types.ts # Shared output/param types (GasInfoOutput, EnsInfoOutput, LogParameters, etc.)
ā āāā tools/
ā āāā public.ts # Logs/fees/tx count utilities
ā āāā ens.ts # ENS resolver utility
āāā build/ # Compiled output
āāā tests/ # Test files
Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
Type Safety Notes
- All
as never
assertions were removed in favor of specific viem types (e.g.,BlockTag
,Abi
, typed params for contract actions). - Generic
Record<string, unknown>
outputs were replaced with named interfaces:GasInfoOutput
,EnsInfoOutput
,Erc20InfoOutput
,ContractStateOutput
,ChainInfoOutput
.
viemGetLogs
parameters are typed viaLogParameters
withfromBlock/toBlock
asbigint | BlockTag
.- Prompts use explicit zod parsing of raw args to avoid unsafe casts while satisfying MCP SDK constraints.
License
MIT
Acknowledgements
- viem - TypeScript Interface for Ethereum
- Model Context Protocol - MCP specification by Anthropic