Solana Web3.js MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to develop and deploy Solana smart contracts end-to-end. This server acts as a bridge between AI language models and the Solana blockchain, providing a standardized interface for blockchain interactions.

> Important Update: This project is currently being migrated from Solana web3.js v1.x to v2.0 to take advantage of improved performance, better type safety, and modern functional programming patterns. See the migration plan for details.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to access external tools and data sources in a secure, controlled manner. This server implements the MCP specification to expose Solana blockchain functionality to AI assistants.

What This Server Does

This MCP server provides AI assistants with the ability to:

1. Interact with the Solana Blockchain: Query account data, check balances, view transaction history, and get network status from various Solana clusters (mainnet, testnet, devnet)

2. Create and Manage Transactions: Build, simulate, sign, and send transactions to the Solana blockchain with proper error handling and fee estimation

3. Develop Smart Contracts: Access templates, compile, test, and deploy Solana programs written in Rust using the Solana SDK or Pinocchio framework

4. Manage Wallets and Keys: Generate keypairs, derive addresses, and interact with wallet adapters while maintaining security best practices

5. Work with Tokens: Create, transfer, and manage SPL tokens and token accounts

Architecture

The server exposes three types of MCP capabilities:

• Tools: Functions that perform actions like sending transactions, deploying programs, or generating keypairs
• Resources: Data sources such as documentation, code templates, and blockchain state information
• Prompts: Templates for guiding the AI through complex workflows like smart contract development

All blockchain interactions are performed through the @solana/web3.js library and related SDKs, with the MCP server acting as a secure intermediary between the AI and the blockchain.

Installation

# Clone the repository
git clone https://github.com/FrankGenGo/solana-web3js-mcp-server.git
cd solana-web3js-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

Usage with Claude Desktop

1. Install Claude Desktop

2. Add the following to your Claude Desktop configuration file:

On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

On Windows: `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "solana": {
      "command": "node",
      "args": ["/absolute/path/to/solana-web3js-mcp-server/dist/index.js"]
    }
  }
}

3. Restart Claude Desktop

4. You can now ask Claude to perform Solana-related tasks, such as:

Security Considerations

• This server does NOT store private keys by default
• Sensitive operations (signing, deploying to mainnet) require explicit user approval
• The server follows best practices for secure blockchain interactions

Available Tools

Account Management (Implemented)

• `getAccountInfo`: Fetch and decode account information
• `checkAccountBalance`: Get SOL balance for an address
• `findProgramAccounts`: Find accounts owned by a program
• `getRentExemption`: Calculate minimum balance for rent exemption

Transaction Management (Implemented)

• `createTransaction`: Build a transaction with specified instructions
• `signTransaction`: Sign a transaction with one or more keypairs
• `sendTransaction`: Send and confirm a transaction on-chain
• `simulateTransaction`: Simulate a transaction without sending it
• `getTransactionStatus`: Check the status of a transaction

Key Management (Implemented)

• `generateKeypair`: Create a new Solana keypair
• `importKeypair`: Import an existing keypair from various formats
• `deriveKeypair`: Derive a keypair from seed, mnemonic, or path

Program Development (Implemented)

• `deployProgram`: Deploy a program to a Solana cluster
• `upgradeProgram`: Upgrade an existing upgradeable program
• `generateProgramAddress`: Derive a program derived address (PDA)

Token Operations (Implemented)

• `createToken`: Create a new SPL token
• `mintTokens`: Mint tokens to a token account
• `transferTokens`: Transfer tokens between accounts
• `getTokenAccountInfo`: Get token account information
• `getTokenSupply`: Get the total supply of a token

Configuration Management (Planned)

• `getConfig`: Get current configuration settings
• `setConfig`: Update configuration parameters
• `getClusterVersion`: Get Solana cluster version

Extended Keypair Management (Planned)

• `saveKeypair`: Save keypair to secure storage
• `recoverKeypair`: Recover keypair from seed phrase
• `verifyKeypair`: Verify keypair integrity

Network Interaction (Planned)

• `requestAirdrop`: Request SOL from devnet/testnet faucet
• `manageStake`: Create and manage stake accounts
• `getValidators`: Get validator information

Blockchain Data Inspection (Planned)

• `getBlock`: Get block details by slot number
• `getBlockProduction`: Get block production statistics
• `getRecentBlockhash`: Get recent blockhash with fee calculator
• `getEpochInfo`: Get current epoch information
• `getInflationRate`: Get current inflation rate

Logging & Monitoring (Planned)

• `getLogs`: Stream and filter transaction logs
• `getProgramLogs`: Monitor program execution logs

Development

# Run in development mode (with auto-reload)
npm run dev

# Run tests (including integration tests against devnet)
npm test

# Lint the code
npm run lint

Setting Up Test Environment

The test suite includes integration tests that run against the Solana devnet. To set up your environment for testing:

1. Install Solana CLI: Follow the official installation instructions

2. Generate a test keypair:

mkdir -p ~/solana-web3js-tests
   solana-keygen new --force --no-bip39-passphrase -o ~/solana-web3js-tests/test-keypair.json

3. Fund the test keypair with devnet SOL:

solana airdrop 1 $(solana address -k ~/solana-web3js-tests/test-keypair.json) --url devnet

4. Verify the balance:

solana balance -k ~/solana-web3js-tests/test-keypair.json --url devnet

The test suite will automatically use this keypair for integration tests against devnet.

Project Structure

• `src/index.ts`: Main entry point (implemented)
• `src/solana-server.ts`: Core server implementation (implemented)
• `src/core/connection-manager.ts`: Solana connection management (implemented)
• `src/transport/`: Transport layer implementations
  • `src/transport/stdio.ts`: Standard I/O transport (implemented)
  • `src/transport/http.ts`: HTTP/SSE transport (implemented)
  • `src/transport/index.ts`: Transport exports (implemented)
• `src/tools/`: Tool implementations for Solana operations
  • `src/tools/accounts/`: Account management tools (implemented)
  • `src/tools/transactions/`: Transaction operations tools (implemented)
  • `src/tools/keys/`: Key management tools (implemented)
  • `src/tools/programs/`: Program development tools (implemented)
• `src/resources/`: Resource implementations for Solana data (planned)
• `src/prompts/`: Reusable prompts for common workflows (planned)
• `src/types/`: TypeScript type definitions
  • `src/types/solana.ts`: Solana-specific type definitions (partial implementation)
  • `src/types/tools.ts`: Tool input/output type definitions (planned)
  • `src/types/config.ts`: Configuration type definitions (planned)
• `src/utils/`: Utility functions and classes
  • `src/utils/errors.ts`: Error handling system (implemented)
  • `src/utils/logging.ts`: Logging system (implemented)

Extending the Server

This server is designed to be extensible. To add new functionality:

1. Create a new tool in the appropriate file in the `tools` directory

2. Register the tool in `solana-server.ts`

3. Test the tool with both unit tests and integration tests

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT