Image description

Hey Dev community! 👋

Ever wished your AI assistant could directly interact with the blockchain? Imagine telling Claude AI to check your Solana balance, swap tokens on Jupiter, or even deploy a new SPL token, and it just does it.

Well, wish no more! With the Agentipy MCP Server, you can bridge the gap between powerful AI models like Claude and the Solana ecosystem. This tutorial will guide you, step-by-step, through setting up this server, which acts as the engine enabling Claude (conceptually, your MEDUSA client) to wield a suite of Solana tools.

Ready to give your AI some serious Web3 superpowers? Let's dive in!

GitHub Repo: niceberginc/agentipy-mcp

Table of Contents

  1. What is the Agentipy MCP Server?
  2. Prerequisites
  3. Installation
  4. Configuration: Setting up Your Server & MEDUSA Client
  5. Running the Server
  6. Available Tools for MEDUSA
  7. How MEDUSA Uses the Tools (Conceptual)
  8. 🚨 Security First!
  9. Troubleshooting Tips
  10. Code Deep Dive (Optional)
  11. Contributing & License

What is the Agentipy MCP Server?

This server implements the Model Context Protocol (MCP), a standard way for AI models to access external tools and context. Specifically, this server uses the excellent agentipy Python library to provide Claude Desktop with a rich set of tools for:

  • ✅ Checking Solana wallet balances (SOL & SPL Tokens)
  • ✅ Transferring SOL & SPL Tokens
  • ✅ Deploying new SPL Tokens
  • ✅ Trading tokens via Jupiter Aggregator
  • ✅ Staking SOL via Jupiter LSTs
  • ✅ Getting price predictions from Allora Network
  • ✅ Performing cross-chain swaps via deBridge
  • ✅ Fetching real-time prices from Pyth Network
  • ✅ Accessing comprehensive token data from CoinGecko (info, prices, trending)

Think of it as a secure translator: Claude (MEDUSA) makes a request in a format MCP understands, and the server uses Agentipy to execute the corresponding action on the Solana blockchain.

Prerequisites

Before we start, make sure you have:

  • 💻 Python: v3.8 or higher
  • 🤖 Claude Desktop: Installed
  • 🔑 Solana Wallet Private Key: Crucially, use a dedicated burner wallet with limited funds for this, NOT your main wallet.
  • ⚡ Solana RPC URL: (e.g., from QuickNode, Alchemy, Helius, Triton, or public endpoints for testing)
  • 🔧 Git: For cloning the repo
  • (Optional) API Keys:
    • ALLORA_API_KEY: For Allora price predictions
    • COINGECKO_PRO_API_KEY: For full CoinGecko functionality (some tools might work on the free tier)
    • OPENAI_API_KEY: Potentially for future Agentipy features

Installation

Get the server code onto your machine.

Option 1: Quick Install (Recommended) 

# 1. Clone the repository
git clone https://github.com/niceberginc/agentipy-mcp
cd agentipy-mcp
# 2. Create & activate virtual environment
python -m venv .venv
# macOS/Linux:
source .venv/bin/activate
# Windows:
.\.venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt

# 4. Proceed to Configuration!

Option 2: Manual Setup
If you prefer setting things up piece by piece:

# 1. Create a project directory
mkdir my-agentipy-mcp && cd my-agentipy-mcp

# 2. Create & activate virtual environment
python -m venv .venv
# macOS/Linux: source .venv/bin/activate
# Windows: .\.venv\Scripts\activate

# 3. Install required packages
pip install agentipy>=2.0.8 python-dotenv>=0.17.1 mcp>=1.4.0 cryptography>=3.4.7 web3>=7.8.0 allora_sdk>=0.2.0

# 4. Manually create server.py, run_mcp.sh/bat from the repo
#    (Cloning in Option 1 is much easier!)
# 5. Proceed to Configuration!
Configuration: Setting up Your Server & MEDUSA Client

Two parts to configure: the server's environment and telling Claude Desktop how to talk to it.

  1. Server Environment (.env)

In the root of your agentipy-mcp directory, create a file named .env and add your credentials. Never commit this file to Git!

# .env - Keep this file secure!

# --- Required ---
# Use a BURNER wallet private key, not your main one!
SOLANA_PRIVATE_KEY=YOUR_SECURE_WALLET_PRIVATE_KEY_HERE
# Your chosen Solana RPC endpoint
RPC_URL=https://api.mainnet-beta.solana.com # Example - Replace with yours!
# --- Optional ---
# Uncomment and add keys if using these tools
# ALLORA_API_KEY=sk_your_allora_key_here
# COINGECKO_PRO_API_KEY=cg_your_coingecko_key_here
# OPENAI_API_KEY=sk_your_openai_key_here
  1. Claude Desktop Integration (MEDUSA Client Setup)

Now, let's tell Claude Desktop about our local MCP server.

A. Find Claude's Config File: 

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Image description

B. Edit the Config File: 

Open claude_desktop_config.json (create it if it doesn't exist). Add the following mcpServers configuration. Pay close attention to the command path!

{
  "mcpServers": {
    "agentipy": {
      "command": "/path/to/your/run_mcp.sh",
      "env": {
        "RPC_URL": "your_solana_rpc_url_here",
        "SOLANA_PRIVATE_KEY": "your_private_key_here",
        "OPENAI_API_KEY": "your_openai_api_key",
        "ALLORA_API_KEY": "your_allora_api_key",
        "COINGECKO_PRO_API_KEY": "your_coingecko_api_key"
      },
      "disabled": false,
      "autoApprove": ["GET_BALANCE", "GET_PRICE_PREDICTION"]
    }
  }
}

Key Points:

  1. command: Must be the correct, full, absolute path to run_mcp.sh (Mac/Linux) or run_mcp.bat (Windows) in your cloned agentipy-mcp folder.
  2. env: Best practice is to let the run script load the .env file. Only add overrides here if necessary.
  3. autoApprove: Powerful but risky. Only list tools you fully trust the AI to execute without prompting you. Start with read-only tools.

C. Restart Claude Desktop:

Save the config file and fully restart Claude Desktop for the changes to take effect.

D. Running the Server

Your MCP server needs to be running in the background for Claude to use its tools.

  1. Open your terminal/command prompt.
  2. cd into your agentipy-mcp project directory.
  3. Activate the virtual environment:
  4. Mac/Linux: source .venv/bin/activate
  5. Windows: ..venv\Scripts\activate

Start the server: 

Mac/Linux: ./run_mcp.sh
Windows: run_mcp.bat

You should see logs indicating the server started and which tools are available. Keep this terminal running!

Image description

Example Output

Image description

Here's a rundown of the blockchain superpowers you've just given AgentiPY MCP Server:

Image description

Native Solana Actions

  • GET_BALANCE: Check wallet balance (SOL or SPL). Input: token_address (optional)
  • TRANSFER: Send SOL or SPL tokens. Input: amount, to (recipient), mint (optional SPL token)
  • DEPLOY_TOKEN: Create a new SPL token. Input: decimals

Allora Actions (ALLORA_API_KEY needed)

  • GET_PRICE_PREDICTION: Fetch BTC/ETH price predictions. Input: asset, timeframe
  • GET_ALL_TOPICS: List available Allora prediction topics. Input: None
  • GET_INFERENCE_BY_TOPIC_ID: Get data for a specific topic. Input: topic_id

Jupiter Actions

  • TRADE_WITH_JUP: Swap tokens using Jupiter Aggregator. Input: input_mint, output_mint, input_amount, slippage_bps
  • STAKE_WITH_JUP: Stake SOL for a Jupiter LST. Input: amount

DeBridge Actions

  • CREATE_DEBRIDGE_TRANSACTION: Initiate a cross-chain swap. (Complex inputs)
  • EXECUTE_DEBRIDGE_TRANSACTION: Execute a created swap. (Requires identifiers)
  • CHECK_TRANSACTION_STATUS: Check swap status. (Requires identifiers)

Pyth Actions

  • PYTH_GET_PRICE: Get real-time asset prices from Pyth Network. Input: asset_symbol (e.g., "SOL")

CoinGecko Actions (COINGECKO_PRO_API_KEY recommended)

  • COINGECKO_GET_TOKEN_INFO: Get detailed token data. Input: token_id (e.g., "solana")
  • COINGECKO_GET_COIN_PRICE_VS: Get price vs. currencies. Input: token_id, vs_currencies (e.g., "usd,eur")
  • COINGECKO_GET_TOP_GAINERS: Find top-performing tokens. (Optional inputs)
  • COINGECTO_GET_TRENDING_POOLS: List trending liquidity pools. Input: None
  • COINGECKO_GET_TRENDING_TOKENS: See what tokens are trending. Input: None
  • COINGECKO_GET_TOKEN_PRICE_DATA: Get historical price data. Input: token_id, vs_currency, days
  • COINGECKO_GET_LATEST_POOLS: Find newly listed pools. Input: None

How MCP Uses the AgentiPY Tools (Conceptual)

Now, in Claude Desktop, you can start making requests!

video camera 00:48
alhibb

agentipy MCP

Alhibb ・ Apr 12

#emptystring

Remember, if a tool isn't in autoApprove, Claude will ask for your confirmation before running it via the MCP server.

🚨 Security First!

This is powerful stuff, so safety is critical:

  • 🛡️ USE A BURNER WALLET: I can't stress this enough. Configure the server with a private key for a wallet holding only the funds you're willing to risk for AI experiments. NEVER use your main savings wallet key.
  • 🔒 Protect .env: Keep your .env file secure and out of version control (add it to .gitignore).
  • 👀 Monitor Activity: Check the MCP server logs and your burner wallet's transactions on Solscan/Explorer regularly.
  • 🚦 autoApprove Wisely: Be extremely selective about which tools you auto-approve. Start with read-only tools. Review often.
  • 🧪 Test on Devnet/Testnet: Use Solana devnet or testnet RPCs in your .env file for initial testing before moving to mainnet-beta.
  • ⬆️ Keep Updated: Regularly update agentipy (pip install -U agentipy) for the latest features and security patches.

Troubleshooting Tips

  • Hitting snags? Try these common fixes:
  • Server Not Connecting?
  • Is the server running in a terminal with the venv active? Check its logs for errors.
  • Is the command path in claude_desktop_config.json exactly correct (absolute path)?
  • Did you restart Claude Desktop fully after editing its config?
  • Check Claude's own logs for MCP connection errors.
  • Tool Errors?

Check the MCP server terminal output for specific error messages (e.g., Insufficient funds, Invalid RPC URL, API key error).

  • Is your .env file correct and saved in the project root?
  • Are required API keys present in .env if using Allora/CoinGecko tools?
  • Is your RPC URL valid and reachable? Public ones can be flaky.
  • Installation Issues?
  • Did you activate the virtual environment (.venv) before pip install?

Try reinstalling dependencies: pip install -r requirements.txt

Curious about the internals?

server.py: The heart of the server. It initializes SolanaAgentKit from Agentipy with your .env credentials and starts the FastMCP server, registering all the tools defined in agentipy/mcp/.

server.py (Simplified) 

import os
from agentipy import SolanaAgentKit
from agentipy.mcp.mcp_server import start_mcp_server, ALL_ACTIONS
from dotenv import load_dotenv

load_dotenv() # Load .env variables

agent = SolanaAgentKit( # Create the Agentipy core object
    private_key=os.getenv("SOLANA_PRIVATE_KEY"),
    rpc_url=os.getenv("RPC_URL"),
    # ... potentially other keys ...
)

# ALL_ACTIONS contains Tool definitions (name, desc, input, handler)
start_mcp_server(agent, ALL_ACTIONS) # Start the MCP listener
- run_mcp.sh / run_mcp.bat: Simple scripts to activate the virtual environment and run server.py.

- requirements.txt: Lists Python dependencies (agentipy, mcp, python-dotenv, etc.).

- agentipy/mcp/ (within Agentipy library): Contains the actual tool definitions (Tool objects) mapping names like GET_BALANCE to their corresponding Agentipy functions (BalanceFetcher.get_balance, etc.).

Contributing & License

  1. Found a bug or want to add a feature? Contributions are welcome! Fork the repo, make your changes, and open a Pull Request.

Repo: https://github.com/niceberginc/agentipy-mcp

License: MIT

That's it! You now have a locally running MCP server empowering Claude (your MEDUSA client) with a versatile set of Solana tools. Go experiment, see what you can build, and share your experiences in the comments below! What cool things will you have MEDUSA do first?