embetter/solana-helius-mcp

Solana MCP Server (Helius Integration)

A Model Context Protocol (MCP) server that provides Solana blockchain tools powered by Helius APIs for use with Cursor and other MCP-compatible clients.

Features

This MCP server provides the following Solana blockchain tools powered by Helius:

• get_solana_balance: Get SOL balance of a wallet address
• get_token_balance: Get token balance for a specific token account
• get_account_info: Get detailed information about a Solana account
• get_recent_transactions: Get recent transactions for a wallet address
• get_token_accounts: Get all token accounts for a wallet address
• validate_address: Validate if a string is a valid Solana address
• get_transaction_details: Get detailed information about a specific transaction by its signature/hash
• get_enhanced_transaction: Get enhanced transaction details using Helius enhanced API
• get_nft_metadata: Get NFT metadata using Helius API
• get_parsed_account_history: Get parsed account history using Helius API
• resolve_token_address: Resolve a token symbol to its address and metadata (e.g., HNT, USDT, BONK)
• get_available_tokens: Get list of all available token symbols that can be resolved
• search_tokens: Search for tokens by partial symbol or name match
• get_token_transactions: Get recent transactions for a specific SPL token mint address
• get_token_transactions_by_symbol: Get recent transactions for a token by its symbol (e.g., HNT, USDT)
• get_wallet_token_transfers: Get detailed token transfer history for a specific wallet showing sent/received amounts

Installation

1. Clone this repository:

git clone <your-repo-url>
cd solana-mcp

2. Install dependencies:

npm install

3. Set up your Helius API key:

export HELIUS_API_KEY="your-helius-api-key-here"

4. Build the project:

npm run build

Usage

Running the Server

You can run the server in development mode:

npm run dev

Or build and run the production version:

npm run build
npm start

Running Tests

The project includes comprehensive tests for the Helius integration:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run specific transaction history tests
npm run test:tx-history

# Run specific token feature tests
npm run test:tokens

The transaction history tests specifically test the wallet address AfwPkfA79MrLEb6GHzzvRVXF8DVzNoawATMnzDghYWRR and verify:

• Basic transaction fetching (recent 10 transactions)
• Detailed transaction information
• Helius enhanced transaction features
• Token account fetching
• SOL balance checking

Using with Cursor

1. In Cursor, go to Settings (Cmd/Ctrl + ,)
2. Navigate to the MCP section
3. Add a new MCP server with the following configuration:
   • Name: Solana MCP Server
   • Command: node /path/to/your/solana-mcp/dist/index.js
   • Args: (leave empty)

Example Usage

Once connected to Cursor, you can use the Solana tools in your conversations:

• "Check the balance of wallet address 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
• "Get recent transactions for 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
• "Validate this address: 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
• "Get token accounts for 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
• "Get transaction details for signature 5KKsC3qjGJTRuDQCRyE2STLJMsJz2DKBmDuYfUxSnthLxfuQoNqHNS1Tmnwq4jECNo71StEVFcEXvKt3QyJtruj6"
• "Resolve token address for HNT"
• "Get recent transactions for USDT token"
• "Search for tokens containing 'BONK'"
• "Get available token symbols"
• "Get detailed token transfer history for wallet AfwPkfA79MrLEb6GHzzvRVXF8DVzNoawATMnzDghYWRR"
• "Show HNT token transfers for wallet AfwPkfA79MrLEb6GHzzvRVXF8DVzNoawATMnzDghYWRR"

Available Tools

get_solana_balance

Get the SOL balance of a wallet address.

Parameters:

• address (string): The wallet address to check balance for

Example:

{
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

get_token_balance

Get the token balance for a specific token account.

Parameters:

• tokenAccount (string): The token account address

get_account_info

Get detailed information about a Solana account.

Parameters:

• address (string): The account address to get info for

get_recent_transactions

Get recent transactions for a wallet address.

Parameters:

• address (string): The wallet address to get transactions for
• limit (number, optional): Number of transactions to retrieve (default: 10)

get_token_accounts

Get all token accounts for a wallet address.

Parameters:

• address (string): The wallet address to get token accounts for

validate_address

Validate if a string is a valid Solana address.

Parameters:

• address (string): The address to validate

get_transaction_details

Get detailed information about a specific transaction by its signature/hash.

Parameters:

• signature (string): The transaction signature/hash to get details for

Example:

{
  "signature": "5KKsC3qjGJTRuDQCRyE2STLJMsJz2DKBmDuYfUxSnthLxfuQoNqHNS1Tmnwq4jECNo71StEVFcEXvKt3QyJtruj6"
}

Returns:

• Transaction signature, slot, block time, fee, status, error details
• Account information and balance changes
• Token balance changes
• Log messages from the transaction

get_enhanced_transaction

Get enhanced transaction details using Helius enhanced API.

Parameters:

• signature (string): The transaction signature/hash to get enhanced details for

Example:

{
  "signature": "5KKsC3qjGJTRuDQCRyE2STLJMsJz2DKBmDuYfUxSnthLxfuQoNqHNS1Tmnwq4jECNo71StEVFcEXvKt3QyJtruj6"
}

get_nft_metadata

Get NFT metadata using Helius API.

Parameters:

• mint (string): The NFT mint address

Example:

{
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}

get_parsed_account_history

Get parsed account history using Helius API.

Parameters:

• address (string): The account address
• limit (number, optional): Number of transactions to retrieve (default: 10)

Example:

{
  "address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
  "limit": 5
}

resolve_token_address

Resolve a token symbol to its address and metadata.

Parameters:

• symbol (string): The token symbol (e.g., HNT, USDT, BONK)

Example:

{
  "symbol": "HNT"
}

Response:

{
  "symbol": "HNT",
  "name": "Helium Network Token",
  "address": "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
  "decimals": 8
}

get_available_tokens

Get list of all available token symbols that can be resolved.

Parameters: None

Example:

{}

Response:

["USDT", "USDC", "DAI", "RAY", "SRM", "BONK", "WIF", "HNT", "MOBILE", "IOT", "PYTH", "JUP", "ORCA", "SAMO"]

search_tokens

Search for tokens by partial symbol or name match.

Parameters:

• query (string): Partial token symbol or name to search for

Example:

{
  "query": "Helium"
}

get_token_transactions

Get recent transactions for a specific SPL token mint address.

Parameters:

• mintAddress (string): The token mint address
• limit (number, optional): Number of transactions to retrieve (default: 10)

Example:

{
  "mintAddress": "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
  "limit": 5
}

get_token_transactions_by_symbol

Get recent transactions for a token by its symbol.

Parameters:

• symbol (string): The token symbol (e.g., HNT, USDT, BONK)
• limit (number, optional): Number of transactions to retrieve (default: 10)

Example:

{
  "symbol": "HNT",
  "limit": 5
}

Enhanced Response (includes transfer details):

[
  {
    "signature": "...",
    "slot": 123456789,
    "blockTime": 1234567890,
    "status": "Success",
    "fee": 5000,
    "tokenInfo": {
      "symbol": "HNT",
      "name": "Helium Network Token",
      "address": "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
      "decimals": 8
    },
    "tokenTransfers": [
      {
        "account": "wallet_address_1",
        "change": 10.5,
        "direction": "received",
        "amount": 10.5,
        "preBalance": 0,
        "postBalance": 10.5
      },
      {
        "account": "wallet_address_2", 
        "change": -10.5,
        "direction": "sent",
        "amount": 10.5,
        "preBalance": 100,
        "postBalance": 89.5
      }
    ]
  }
]

get_wallet_token_transfers

Get detailed token transfer history for a specific wallet address showing sent/received amounts.

Parameters:

• walletAddress (string): The wallet address to get token transfer history for
• symbol (string, optional): Filter by specific token symbol (e.g., HNT, USDT)
• limit (number, optional): Number of transactions to retrieve (default: 10)

Example:

{
  "walletAddress": "AfwPkfA79MrLEb6GHzzvRVXF8DVzNoawATMnzDghYWRR",
  "symbol": "HNT",
  "limit": 5
}

Response:

[
  {
    "signature": "...",
    "slot": 123456789,
    "blockTime": 1234567890,
    "status": "Success",
    "fee": 5000,
    "transfers": [
      {
        "mint": "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux",
        "tokenSymbol": "HNT",
        "tokenName": "Helium Network Token",
        "change": 5.25,
        "direction": "received",
        "amount": 5.25,
        "preBalance": 10.5,
        "postBalance": 15.75,
        "decimals": 8
      }
    ]
  }
]

Enhanced Transfer Details

The enhanced token transaction functions now provide detailed transfer information including:

Transfer Direction

• direction: "sent" or "received" - indicates whether tokens were sent from or received by the wallet
• change: Positive or negative number showing the net change in token balance
• amount: Absolute value of the transfer amount

Balance Tracking

• preBalance: Token balance before the transaction
• postBalance: Token balance after the transaction
• decimals: Token decimal places for accurate amount display

Wallet Information

• account: Wallet address involved in the transfer
• mint: Token mint address
• tokenSymbol: Human-readable token symbol (e.g., "HNT", "USDT")
• tokenName: Full token name (e.g., "Helium Network Token")

Example Use Cases

• Track token inflows and outflows for a specific wallet
• Analyze trading patterns and token movements
• Monitor token balances before and after transactions
• Identify which wallets sent/received tokens in a transaction

Supported Tokens

The following tokens are supported for symbol resolution:

• Stablecoins: USDT, USDC, DAI
• DeFi Tokens: RAY (Raydium), SRM (Serum)
• Meme Tokens: BONK, WIF (dogwifhat)
• Infrastructure: HNT (Helium Network Token), MOBILE (Helium Mobile), IOT (Helium IOT)
• Gaming: PYTH (Pyth Network), JUP (Jupiter)
• Other: ORCA, SAMO (Samoyedcoin)

Development

Project Structure

solana-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Scripts

• npm run dev: Run in development mode with hot reload
• npm run build: Build the TypeScript project
• npm start: Run the built server
• npm test: Run tests
• npm run lint: Run ESLint
• npm run format: Format code with Prettier

Adding New Tools

To add a new Solana tool:

1. Add the tool definition to the tools array in src/index.ts
2. Implement the tool function
3. Add a case in the call_tool handler switch statement

Example:

// Add to tools array
{
  name: 'my_new_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param1: {
        type: 'string',
        description: 'Description of parameter'
      }
    },
    required: ['param1']
  }
}

// Implement the function
async function myNewTool(param1: string): Promise<string> {
  // Implementation here
  return 'Result';
}

// Add to switch statement
case 'my_new_tool':
  result = await myNewTool(args.param1);
  break;

Configuration

The server connects to Solana mainnet via Helius by default. To change the network or API provider, modify the connection URL in src/index.ts:

// For Helius mainnet (default)
const connection = new Connection(`https://rpc.helius.xyz/?api-key=${HELIUS_API_KEY}`, 'confirmed');

// For Helius devnet
const connection = new Connection(`https://rpc-devnet.helius.xyz/?api-key=${HELIUS_API_KEY}`, 'confirmed');

// For standard Solana RPC (fallback)
const connection = new Connection('https://api.mainnet-beta.solana.com', 'confirmed');

Error Handling

The server includes comprehensive error handling for:

• Invalid Solana addresses
• Network connection issues
• RPC errors
• Invalid tool parameters

All errors are returned as text responses with error details.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.