@gala-chain/launchpad-mcp-server

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

🚀 Features

• 41 AI-accessible tools for complete Gala Launchpad integration
• 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

📦 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 (41 Total)

Pool Management (8 tools)

• gala_launchpad_fetch_pools - Fetch token pools with filtering
• gala_launchpad_fetch_pool_details - Get detailed pool state
• 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_check_token_name - Check name availability
• gala_launchpad_check_token_symbol - Check symbol availability
• gala_launchpad_resolve_vault_address - Get GalaChain vault address

Trading Operations (8 tools)

• gala_launchpad_calculate_buy_amount - Calculate buy amounts
• gala_launchpad_calculate_sell_amount - Calculate sell amounts
• 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_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

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 (2 tools)

• 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

💡 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"

📚 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
• 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