mcp-blockchain

This MCP server exposes blockchain-related operations as tools that AI assistants can invoke within a conversation. Core capabilities include listing supported networks, querying balances, reading data from verified smart contracts, preparing unsigned transactions for user approval, and checking the status of submitted transactions. The server is designed so that private keys never leave the user's wallet; the DApp handles wallet connection and signing, while the MCP server focuses on data access and transaction preparation. Typical workflows involve an AI assistant requesting data or a transaction, the server returning an unsigned transaction or on-chain data, and the user reviewing and approving actions via the Web DApp.

To use the tools, an AI assistant would call tools such as: get-chains to discover networks, get-balance to fetch an account balance, read-contract to query contract state, prepare-transaction to generate an unsigned transaction for user approval, and get-transaction-status to monitor outcomes. Example usage shows calling get-balance with a chainId and address to fetch a balance, enabling the assistant to present accurate information before proceeding with a user-approved action.

Prerequisites:

• Node.js v18+ (or an environment where you plan to run the server)
• npm or yarn
• PostgreSQL database
• Redis (optional, for caching)
• Infura API key (for blockchain access)
• Etherscan API key (for contract ABIs)

Installation steps:

1. Clone the repository and install dependencies

git clone https://github.com/zhangzhongnan928/mcp-blockchain-server.git
cd mcp-blockchain-server
npm install
# or
yarn install

2. Configure environment

• Create a .env file in the project root (or copy from .env.example) and fill in values

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

3. Set up the database

# Create the PostgreSQL database (name can vary per config)
createdb mcp_blockchain

# Run migrations to set up schema
npm run db:migrate
# or
yarn db:migrate

4. Start the server

npm run dev
# or
yarn dev

5. Optional: Docker Compose quickstart

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

docker-compose up -d

This will launch PostgreSQL, Redis, the MCP Server, and the Web DApp stack.

Environment variables and configuration:

• Ensure DATABASE_URL and REDIS_URL are reachable from the server environment.
• INFURA_API_KEY and ETHERSCAN_API_KEY are used for blockchain access and contract ABIs; keep them secure.
• JWT_SECRET protects token integrity; consider using a strong, unique secret in production.
• If using Docker, ensure docker-compose.yml is configured with correct environment variables and network settings. Common issues:
• Connection errors to PostgreSQL/Redis: verify network accessibility and credentials in .env.
• API keys not authorized: check key permissions and rate limits with the provider.
• Migrations fail: ensure the database user has permissions and the correct database name matches your config. Security tips:
• HTTPS-only in production and Content Security Policy headers in the DApp.
• Audit logging enabled to track operations for compliance.
• Validate inputs and implement rate limiting to prevent abuse.