Supercharge Claude AI with Solana: Build Your Agentipy MCP Server (MEDUSA Client)

Alhibb — Sat, 12 Apr 2025 05:18:30 +0000

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

What is the Agentipy MCP Server?
Prerequisites
Installation
Configuration: Setting up Your Server & MEDUSA Client
Running the Server
Available Tools for MEDUSA
How MEDUSA Uses the Tools (Conceptual)
🚨 Security First!
Troubleshooting Tips
Code Deep Dive (Optional)
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.

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

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

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:

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.
env: Best practice is to let the run script load the .env file. Only add overrides here if necessary.
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.

Open your terminal/command prompt.
cd into your agentipy-mcp project directory.
Activate the virtual environment:
Mac/Linux: source .venv/bin/activate
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!

Example Output

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

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!

00:48

Alhibb

Apr 12 '25

agentipy MCP

#emptystring

Comments

1 min read

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

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?

agentipy MCP

Alhibb — Sat, 12 Apr 2025 05:09:34 +0000

Forem: Alhibb

Supercharge Claude AI with Solana: Build Your Agentipy MCP Server (MEDUSA Client)

Table of Contents

What is the Agentipy MCP Server?

Prerequisites

Installation

Option 1: Quick Install (Recommended)

A. Find Claude's Config File:

B. Edit the Config File:

C. Restart Claude Desktop:

D. Running the Server

Start the server:

Example Output

How MCP Uses the AgentiPY Tools (Conceptual)

agentipy MCP

🚨 Security First!

Troubleshooting Tips

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

Try reinstalling dependencies: pip install -r requirements.txt

Curious about the internals?

server.py (Simplified)

Contributing & License

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

License: MIT

agentipy MCP