MCP Blockchain Server

MCP Blockchain Server & DApp

A secure system enabling AI assistants to interact with blockchain smart contracts while ensuring users maintain complete control over their private keys and transaction signing.

Overview

This project addresses a key challenge in AI-blockchain integration: allowing AI assistants to read blockchain data and prepare transactions while ensuring users maintain exclusive control over transaction signing and private keys.

The system consists of:

MCP Server: A Model Context Protocol server that exposes blockchain operations as tools that can be used by AI assistants
Web DApp: A React application that provides a user interface for wallet connection and transaction signing
Database: PostgreSQL database for storing users, API keys, and transaction records
Caching: Redis for caching frequently accessed data

Features

MCP Server Features

Blockchain Data Access: Read balances, contract state, and other on-chain data
Transaction Preparation: Create unsigned transactions for user approval
Multi-Chain Support: Works with Ethereum, Polygon, and other EVM-compatible chains
Smart Contract Interaction: Read from verified smart contracts on supported networks
Security-First Design: Private keys never leave the user's wallet

Web DApp Features

Wallet Integration: Connect with MetaMask and other Web3 wallets
Transaction Review: Clear UI for reviewing transaction details before signing
Transaction Signing: Sign transactions with connected wallet
Transaction Tracking: Monitor status of submitted transactions
Mobile Compatibility: Responsive design works on all devices

Security Principles

Private Key Isolation: Keys never leave the user's wallet
Transaction Verification: Clear UI for reviewing transaction details
API Authentication: Secure API key management
Rate Limiting: Prevent abuse
Input Validation: Sanitize all inputs
Audit Logging: Track all operations
HTTPS Only: Secure communications
Content Security Policy: Prevent XSS

Transaction Flow

AI assistant requests transaction through MCP Server
MCP Server prepares unsigned transaction with UUID
MCP Server returns transaction URL to AI assistant
AI assistant provides URL to user
User opens URL in browser
User connects wallet and reviews transaction details
User approves and signs transaction with their wallet
Web DApp submits signed transaction to blockchain
Transaction status is updated and tracked

Getting Started

Prerequisites

Node.js (v18 or higher)
npm or yarn
PostgreSQL
Redis (optional, for caching)
Infura API key (for blockchain access)
Etherscan API key (for contract ABIs)

Installation

Clone the repository:

git clone https://github.com/zhangzhongnan928/mcp-blockchain-server.git
cd mcp-blockchain-server

Install dependencies:

npm install
# or
yarn install

Set up environment variables: Create a .env file in the root directory (or copy from .env.example):

cp .env.example .env
# Edit .env with your configurations

Set up the database:

# For detailed instructions, see the Database Setup Guide
# docs/database-setup.md

# Create the PostgreSQL database
createdb mcp_blockchain

# Run database migrations
npm run db:migrate
# or
yarn db:migrate

See Database Setup Guide for detailed instructions on installing and configuring PostgreSQL.

Start the server:

npm run dev
# or
yarn dev

Using Docker Compose

For a quick start using Docker:

# Create .env file with required environment variables
cp .env.example .env
# Edit .env with your configurations

# Start the services
docker-compose up -d

This will start:

PostgreSQL database
Redis cache
MCP Server
Web DApp

Development

Server Structure

src/mcp: MCP server implementation
src/services: Core business logic services
src/utils: Utility functions
src/index.ts: Main entry point

Web DApp Structure

web/src/components: React components
web/src/hooks: Custom React hooks
web/src/services: API services
web/src/pages: Page components

Using the MCP Server

The MCP Server exposes several tools that can be used by AI assistants:

get-chains: Get list of supported blockchain networks
get-balance: Get account balance for an address
read-contract: Read data from a smart contract
prepare-transaction: Prepare an unsigned transaction for user approval
get-transaction-status: Get the current status of a transaction

Example Tool Usage

// Example of using the get-balance tool
const result = await callTool("get-balance", {
  chainId: "1",
  address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
});

Troubleshooting

If you encounter issues with dependencies:

# MCP SDK issue - install directly from GitHub
npm uninstall @modelcontextprotocol/sdk
npm install modelcontextprotocol/typescript-sdk

For database connection issues, see the Database Setup Guide.

License

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

MCP Blockchain Server

Integrations