@gala-chain/launchpad-mcp-server

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

🚀 Features

• 55 AI-accessible tools for complete Gala Launchpad integration (includes 4 price history tools)
• 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

Module Format

The MCP server is built with CommonJS (dist/index.js) and works seamlessly with the SDK's dual-format support:

• MCP Server: CommonJS (Node.js native)
• Underlying SDK: Supports ESM, CommonJS, and UMD
• Compatibility: Full support for both modern and legacy environments

The MCP server automatically uses the correct SDK format for your Node.js version - no configuration needed!

🏁 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)
• MYSQL_CONNECTION_STRING (optional) - MySQL connection string for price history feature (format: mysql://user:password@host:port/database)

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 (52 Total)

Pool Management (15 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_fetch_price_history - Fetch historical price snapshots from MySQL database
• 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.

📊 Historical Price Analysis

gala_launchpad_fetch_price_history - Fetch historical price snapshots for DEX tokens

This tool queries the MySQL price_snapshots database for historical token price data, enabling trend analysis and volatility assessment.

Requirements:

• MySQL connection string must be configured via MYSQL_CONNECTION_STRING environment variable
• Node.js environment only (not available in browser)
• Only works for DEX tokens with price snapshot data

Configuration:

Add to Claude Desktop config:

{
  "mcpServers": {
    "gala-launchpad": {
      "command": "npx",
      "args": ["-y", "@gala-chain/launchpad-mcp-server@latest"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "MYSQL_CONNECTION_STRING": "mysql://user:password@host:3306/database"
      }
    }
  }
}

Parameters:

• tokenId (required) - Token identifier (string format: "collection|category|type|additionalKey" or object with collection, category, type, additionalKey)
• from (optional) - Start date (ISO 8601, defaults to 30 days ago)
• to (optional) - End date (ISO 8601, defaults to now)
• sortOrder (optional) - Sort order: 'ASC' or 'DESC' (default: DESC for newest-first)
• page (optional) - Page number for pagination (default: 1)
• limit (optional) - Results per page, max 100 (default: 10)

Use Cases:

• Historical price analysis and charting
• Price trend identification
• Volatility analysis over time periods
• Data export for external analytics

Example:

Ask Claude:

"Fetch the last 30 days of hourly price data for GUSDC token"

"Show me GALA token price history from the last 7 days with daily snapshots"

📊 All Historical Price Data (Auto-Paginated)

gala_launchpad_fetch_all_price_history - Fetch all historical price snapshots (auto-paginated)

Automatically fetches all pages of historical price data and returns complete dataset in single result.

Use Cases:

• Complete volatility analysis
• Full historical trend analysis
• Statistical calculations on entire dataset
• Data export for backtesting

Example:

Ask Claude:

"Get all price history for GUSDC token from January 2024 and calculate volatility"

💰 Latest Token Prices

gala_launchpad_fetch_prices - Fetch latest prices for all tokens (paginated)

Returns the most recent price snapshot for each unique token in the database.

Use Cases:

• Market overview dashboards
• Price comparison across tokens
• Real-time price monitoring
• Market statistics

Example:

Ask Claude:

"Fetch the latest prices for the top 20 most expensive tokens"

"Show me all token prices sorted alphabetically"

gala_launchpad_fetch_all_prices - Fetch all latest prices (auto-paginated)

Convenience method that automatically paginates through all tokens and returns all latest prices.

Use Cases:

• Complete market analysis
• Market-wide statistics and calculations
• Price monitoring across all tokens
• Data export for analysis tools

Example:

Ask Claude:

"Get all latest token prices and tell me the average price across all tokens"

"Show me the most and least expensive tokens right now"

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