@gala-chain/launchpad-mcp-server

MCP (Model Context Protocol) server for Gala Launchpad SDK - Enables AI agents to interact with Gala Launchpad.

🚀 Features

• 50 AI-accessible tools for complete Gala Launchpad integration
• 14 slash commands (prompts) for quick access to common workflows
• Type-safe - Full TypeScript support with validated inputs
• Production-ready - Built on @gala-chain/launchpad-sdk
• Easy setup - Works with Claude Desktop and other MCP clients
• Comprehensive - Pool management, trading, balances, token creation, comments, transfers
• Optimized - Local bonding curve calculations for instant results

📦 Installation

npm install -g @gala-chain/launchpad-mcp-server

🏁 Quick Start

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gala-launchpad": {
      "command": "npx",
      "args": ["-y", "@gala-chain/launchpad-mcp-server@latest"],
      "env": {
        "PRIVATE_KEY": "0x1234567890abcdef...",
        "ENVIRONMENT": "development"
      }
    }
  }
}

Environment Variables:

• PRIVATE_KEY (required) - Your Ethereum wallet private key
• ENVIRONMENT (optional) - development or production (default: development)
• DEBUG (optional) - true to enable debug logging
• TIMEOUT (optional) - Request timeout in milliseconds (default: 30000)

Using with Claude Desktop

1. Install: npm install -g @gala-chain/launchpad-mcp-server
2. Configure: Add server to claude_desktop_config.json (see above)
3. Restart Claude Desktop
4. Use tools: Ask Claude to interact with Gala Launchpad!

🛠️ Available Tools (50 Total)

Pool Management (14 tools)

• gala_launchpad_fetch_pools - Fetch token pools with filtering
• gala_launchpad_fetch_all_pools - Fetch all available pools with automatic pagination
• gala_launchpad_fetch_pool_details - Get detailed pool state
• gala_launchpad_fetch_pool_details_for_calculation - Get optimized pool details for local calculations
• gala_launchpad_fetch_token_distribution - Get holder distribution
• gala_launchpad_fetch_token_badges - Get achievement badges
• gala_launchpad_fetch_volume_data - Get OHLCV charting data
• gala_launchpad_fetch_token_spot_price - Fetch USD spot price for DEX tokens
• gala_launchpad_fetch_gala_spot_price - Fetch current GALA USD spot price
• gala_launchpad_fetch_launchpad_token_spot_price - Fetch USD spot price for launchpad token
• gala_launchpad_check_token_name - Check name availability
• gala_launchpad_check_token_symbol - Check symbol availability
• gala_launchpad_resolve_vault_address - Get GalaChain vault address
• gala_launchpad_resolve_token_class_key - Get GalaChain TokenClassKey

Trading Operations (13 tools)

• gala_launchpad_calculate_buy_amount - Calculate buy amounts (network call)
• gala_launchpad_calculate_sell_amount - Calculate sell amounts (network call)
• gala_launchpad_calculate_buy_amount_local - Calculate buy amounts (local, instant)
• gala_launchpad_calculate_buy_amount_external - Calculate buy amounts (explicit network call)
• gala_launchpad_calculate_sell_amount_local - Calculate sell amounts (local, instant)
• gala_launchpad_calculate_sell_amount_external - Calculate sell amounts (explicit network call)
• gala_launchpad_buy_tokens - Execute token purchase
• gala_launchpad_sell_tokens - Execute token sale
• gala_launchpad_fetch_trades - Get trade history
• gala_launchpad_calculate_initial_buy - Calculate initial buy
• gala_launchpad_get_bundler_transaction_result - Get transaction status by ID
• gala_launchpad_calculate_buy_amount_for_graduation - Calculate cost to graduate pool
• gala_launchpad_graduate_token - One-step pool graduation

🎓 Understanding Graduation Calculations

CRITICAL: The amount field in gala_launchpad_calculate_buy_amount_for_graduation represents GALA cost, NOT token quantity!

// Example response
{
  "amount": "1594263.41948877",
  "transactionFee": "1594.26341949",
  "gasFee": "1"
}

// ❌ WRONG INTERPRETATION:
// "Need to buy 1,594,263 tokens"

// ✅ CORRECT INTERPRETATION:
// "Need to spend 1,594,263.42 GALA to buy all remaining tokens and graduate the pool"

Amount Field Reference:

Key Points:

• Read the full number as-is - decimal point is NOT shifted
• Graduation amounts are typically in the hundreds of thousands to millions of GALA
• Always use graduate_token for convenience - it handles calculations internally
• Pool status changes from "Ongoing" to "Completed" upon successful graduation

⚡ Performance Optimization for AI Agents

The following tools now support optional performance parameters to reduce network calls by 66% and speed up operations by ~70%:

• gala_launchpad_fetch_launchpad_token_spot_price
• gala_launchpad_calculate_buy_amount_for_graduation
• gala_launchpad_graduate_token

New Optional Parameters:

• calculateAmountMode (enum: 'local' | 'external') - Calculation strategy
• currentSupply (string) - Pre-fetched current token supply

Optimization Pattern:

// ❌ WITHOUT OPTIMIZATION (3 network calls)
const spotPrice1 = await gala_launchpad_fetch_launchpad_token_spot_price({ tokenName: "tinyevil" });
// → Network call #1

const graduation1 = await gala_launchpad_calculate_buy_amount_for_graduation({ tokenName: "tinyevil" });
// → Network call #2

const result1 = await gala_launchpad_graduate_token({ tokenName: "tinyevil" });
// → Network call #3

// ✅ WITH OPTIMIZATION (1 network call + instant local calculations)
// Step 1: Fetch pool details once
const poolDetails = await gala_launchpad_fetch_pool_details_for_calculation({ tokenName: "tinyevil" });
const currentSupply = poolDetails.currentSupply;

// Step 2: Reuse currentSupply for instant local calculations
const spotPrice2 = await gala_launchpad_fetch_launchpad_token_spot_price({
  tokenName: "tinyevil",
  calculateAmountMode: "local",
  currentSupply: currentSupply
});
// → Instant (no network call)

const graduation2 = await gala_launchpad_calculate_buy_amount_for_graduation({
  tokenName: "tinyevil",
  calculateAmountMode: "local",
  currentSupply: currentSupply
});
// → Instant (no network call)

const result2 = await gala_launchpad_graduate_token({
  tokenName: "tinyevil",
  calculateAmountMode: "local",
  currentSupply: currentSupply,
  slippageToleranceFactor: 0.01
});
// → Uses local calculation (no redundant pool fetch)

Performance Impact:

When to Use Optimization:

• ✅ Multiple calculations on the same token
• ✅ Price discovery and analytics
• ✅ Trading bot logic with frequent calculations
• ✅ Simulations and backtests
• ❌ Single one-off calculations (not worth the complexity)

Accuracy: Local calculations match external (network) with <0.01% difference.

Balance & Portfolio (6 tools)

• gala_launchpad_fetch_gala_balance - Get GALA balance
• gala_launchpad_fetch_token_balance - Get token balance
• gala_launchpad_fetch_tokens_held - Get portfolio holdings
• gala_launchpad_fetch_tokens_created - Get created tokens
• gala_launchpad_fetch_profile - Get user profile
• gala_launchpad_update_profile - Update profile

Token Creation (4 tools)

• gala_launchpad_launch_token - Create new token pool
• gala_launchpad_upload_token_image - Upload token image from filesystem
• gala_launchpad_upload_profile_image - Upload profile image from filesystem
• gala_launchpad_fetch_launch_token_fee - Get current GALA fee to launch a token

Comments & Social (2 tools)

• gala_launchpad_post_comment - Post comment on token
• gala_launchpad_fetch_comments - Get token comments

Token Transfers (2 tools)

• gala_launchpad_transfer_gala - Transfer GALA tokens
• gala_launchpad_transfer_token - Transfer launchpad tokens

Utility Tools (9 tools)

• gala_launchpad_create_wallet - Create new GalaChain wallet
• gala_launchpad_get_address - Get user's GalaChain address
• gala_launchpad_get_ethereum_address - Get user's Ethereum address
• gala_launchpad_get_config - Get current SDK configuration
• gala_launchpad_get_url_by_token_name - Generate frontend URL for a token
• gala_launchpad_explain_sdk_usage - Get SDK code examples and usage explanations
• gala_launchpad_is_token_graduated - Check if token completed bonding curve phase
• gala_launchpad_get_cache_info - Get token metadata cache statistics
• gala_launchpad_clear_cache - Clear token metadata cache entries

💡 Example Usage

Ask Claude (or your AI assistant):

"Fetch the 10 most recent token pools on Gala Launchpad"

"What's my GALA balance?"

"Calculate how many tokens I'd get if I buy with 100 GALA on dragnrkti"

"Buy 50 GALA worth of rocketri tokens with 5% slippage"

"Show me all tokens I'm holding"

⚡ Slash Commands (Prompts)

The MCP server exposes 14 slash commands that provide quick access to common Launchpad workflows. These appear as /galachain-launchpad:<<method>> in Claude Desktop.

Trading Commands (4 commands)

/galachain-launchpad:analyze-token

• Comprehensive token analysis (pool details, spot price, graduation cost)
• Arguments: tokenName (required)
• Example: /galachain-launchpad:analyze-token tokenName=anime
• Uses optimized LOCAL calculations for speed

/galachain-launchpad:buy-tokens

• Guided token purchase with slippage protection
• Arguments: tokenName (required), galaAmount (required), slippage (optional, default 1%)
• Example: /galachain-launchpad:buy-tokens tokenName=anime galaAmount=100 slippage=2
• Shows breakdown and asks for confirmation before executing

/galachain-launchpad:sell-tokens

• Guided token sale with slippage protection
• Arguments: tokenName (required), tokenAmount (required), slippage (optional, default 1%)
• Example: /galachain-launchpad:sell-tokens tokenName=anime tokenAmount=1000
• Checks balance and shows breakdown before executing

/galachain-launchpad:graduate-token

• One-step pool graduation workflow
• Arguments: tokenName (required), slippage (optional, default 1%)
• Example: /galachain-launchpad:graduate-token tokenName=anime
• Checks if already graduated, calculates cost, and executes with confirmation

Portfolio Commands (5 commands)

/galachain-launchpad:portfolio

• Complete portfolio analysis with USD values
• Arguments: None
• Shows GALA balance, all token holdings, total portfolio value, and top holdings

/galachain-launchpad:tokens-held

• List all tokens currently held
• Arguments: search (optional fuzzy filter), limit (optional, default 20)
• Example: /galachain-launchpad:tokens-held search=dragon limit=10

/galachain-launchpad:tokens-created

• Show tokens created by the user with status
• Arguments: search (optional), limit (optional, default 20)
• Shows graduation status and progress for each token

/galachain-launchpad:balance

• Check GALA and optional token balance
• Arguments: tokenName (optional)
• Example: /galachain-launchpad:balance tokenName=anime
• Displays both token amounts and USD values

/galachain-launchpad:profile

• Show user profile and activity summary
• Arguments: None
• Displays profile info, wallet addresses, activity metrics, and current balance

Analysis Commands (5 commands)

/galachain-launchpad:compare-tokens

• Side-by-side comparison of two tokens
• Arguments: token1 (required), token2 (required)
• Example: /galachain-launchpad:compare-tokens token1=anime token2=test216253
• Shows comparison table with metrics, holders, and investment analysis

/galachain-launchpad:graduation-status

• Check graduation readiness for multiple tokens
• Arguments: tokens (required, comma-separated)
• Example: /galachain-launchpad:graduation-status tokens=anime,test216253,dragnrkti
• Shows progress table and identifies graduation opportunities

/galachain-launchpad:spot-prices

• Batch spot price lookup for multiple tokens
• Arguments: tokens (required, comma-separated)
• Example: /galachain-launchpad:spot-prices tokens=anime,test216253
• Uses optimized LOCAL calculations for instant results

/galachain-launchpad:pool-details

• Comprehensive pool information with badges and distribution
• Arguments: tokenName (required)
• Example: /galachain-launchpad:pool-details tokenName=anime
• Shows complete pool metrics, achievements, and recent activity

/galachain-launchpad:trade-history

• View recent trades with filtering
• Arguments: tokenName (optional), userAddress (optional), tradeType (optional: BUY/SELL), limit (optional, default 20)
• Example: /galachain-launchpad:trade-history tokenName=anime tradeType=BUY limit=10

Slash Command Benefits

✅ Quick access - Type /galachain-launchpad: to see all available commands ✅ Guided workflows - Each command provides step-by-step execution ✅ Optimized - Uses LOCAL calculations for maximum performance ✅ Safe - Asks for confirmation before executing transactions ✅ Educational - Shows what MCP tools are being used behind the scenes

Example Slash Command Usage

User: /galachain-launchpad:analyze-token tokenName=anime

Claude: I'll analyze the token "anime" using the Gala Launchpad MCP server:

1. Fetching optimized pool details...
   ✅ Current supply: 510,379.79
   ✅ Remaining tokens: 9,489,620.21
   ✅ Max supply: 10,000,000

2. Calculating USD spot price (LOCAL mode - instant!)...
   ✅ Spot price: $0.000153

3. Calculating graduation cost (LOCAL mode - instant!)...
   ✅ GALA required: 1,640,974.33 GALA
   ✅ Transaction fee: 1,640.97 GALA
   ✅ Total cost: 1,642,615.30 GALA

4. Pool progress: 5.10% complete

Analysis:
- Current price is relatively low (early stage token)
- Requires significant GALA (~1.6M) to graduate
- Only 5% through bonding curve - high risk, high potential reward
- Good opportunity for early entry if you believe in the project

📚 SDK Usage Reference

The MCP server includes a built-in SDK documentation tool that provides complete, runnable code examples for using the SDK directly instead of through MCP tools. This is perfect for developers who want to integrate the SDK into their applications.

Ask Claude for SDK code examples:

"Explain how to buy tokens using the SDK"

"Show me the SDK code for selling tokens"

"How do I use multiple wallets with the SDK?"

"Show me all MCP tools and their SDK method equivalents"

Available topics:

• buy-tokens - Complete buying workflow
• sell-tokens - Complete selling workflow
• pool-graduation - Graduate bonding curve pools
• fetch-pools - Query pool data
• balances - Check GALA and token balances
• token-creation - Launch new tokens
• multi-wallet - Multi-wallet patterns
• transfers - Transfer tokens between wallets
• error-handling - Handle exceptions
• installation - Install and configure SDK
• local-calculations - Local vs external bonding curve calculations
• mcp-to-sdk-mapping - Complete tool-to-method mapping

Each topic returns complete TypeScript code with explanations, making it easy to transition from MCP tools to direct SDK integration.

🔐 Multi-Wallet Support

All signing operations support an optional privateKey parameter for per-operation wallet overrides. This enables:

• Testing multi-wallet workflows
• Simulating different user behaviors
• Building multi-agent trading systems
• Operating multiple wallets from a single MCP server

Tools Supporting privateKey Override

Trading Operations:

• gala_launchpad_buy_tokens - Buy tokens from different wallet
• gala_launchpad_sell_tokens - Sell tokens from different wallet

Token Creation:

• gala_launchpad_launch_token - Create token from different wallet
• gala_launchpad_upload_token_image - Upload image for token
• gala_launchpad_upload_profile_image - Upload profile image

Transfer Operations:

• gala_launchpad_transfer_gala - Transfer GALA from different wallet
• gala_launchpad_transfer_token - Transfer tokens from different wallet

Social & Profile:

• gala_launchpad_post_comment - Post comment from different wallet
• gala_launchpad_update_profile - Update profile for different wallet

Example: Multi-Wallet Trading Scenario

Ask Claude:

"Create a scenario where Buster's wallet buys and sells tokens:

1. Send Buster 1000 GALA from the main wallet
2. Have Buster buy 100 GALA worth of tinyevil tokens using his private key: 0x1234...
3. Have Buster sell 50 GALA worth back
4. Check both wallets' final balances"

Claude will use:

// 1. Main wallet sends GALA to Buster
gala_launchpad_transfer_gala({
  recipientAddress: "0xBusterAddress...",
  amount: "1000"
  // No privateKey - uses main wallet
});

// 2. Buster buys tokens with his wallet
gala_launchpad_buy_tokens({
  tokenName: "tinyevil",
  amount: "100",
  type: "native",
  expectedAmount: "50000",
  slippageToleranceFactor: 0.05,
  privateKey: "0x1234..." // Buster's wallet
});

// 3. Buster sells tokens
gala_launchpad_sell_tokens({
  tokenName: "tinyevil",
  amount: "50",
  type: "native",
  expectedAmount: "48",
  slippageToleranceFactor: 0.05,
  privateKey: "0x1234..." // Buster's wallet
});

Private Key Format Requirements

The privateKey parameter must be:

• Format: '0x' + 64 hexadecimal characters
• Example: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
• Invalid: Raw hex without '0x', mnemonics, or addresses

Security Considerations

When using privateKey overrides:

1. Never expose private keys in prompts or logs
2. Use test wallets for development and testing
3. Limit fund amounts in test wallets
4. Monitor operations when testing multi-wallet scenarios
5. Validate addresses before transfers

🔧 Development

Local Development

# Clone repository
git clone https://gitlab.com/gala-games/defi/launchpad/sdk.git
cd launchpad-sdk/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Testing

npm test

📚 Documentation

• MCP Tool Specification - Complete tool reference
• AI Agent Guide - Integration patterns
• SDK Documentation - Underlying SDK reference

🔐 Security

Important Security Notes:

1. Private Keys - Never commit private keys to version control
2. Environment Variables - Store credentials in claude_desktop_config.json securely
3. Wallet Safety - Use separate wallets for development and production
4. Amount Limits - Consider setting up trading limits for automated agents

🐛 Troubleshooting

"SDK not initialized"

• Ensure PRIVATE_KEY is set in environment variables
• Check that private key format is valid (0x + 64 hex characters)

"Tool not found"

• Restart Claude Desktop after configuration changes
• Verify server is listed in Claude Desktop settings

"Connection failed"

• Check DEBUG=true logs for detailed error messages
• Verify network connectivity to Gala Launchpad backends

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

📞 Support

• Issues: GitLab Issues
• Documentation: Full Documentation
• SDK Package: @gala-chain/launchpad-sdk

Built with ❤️ for the Gala ecosystem