launchfast-mcp

<div align="center"> # 🚀 LaunchFast MCP Server **Professional Amazon & Alibaba Research Tools for Claude AI** [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-1.18.2-green.svg)](https://modelcontextprotocol.io/) [![Node](https://img.shields.io/badge/Node-18+-brightgreen.svg)](https://nodejs.org/) **[Features](#-features)** • **[Quick Start](#-quick-start)** • **[Tools](#-available-tools)** • **[Examples](#-usage-examples)** • **[Docs](#-documentation)** </div> --- ## 📖 Overview LaunchFast MCP Server brings **enterprise-grade Amazon and Alibaba intelligence** directly into your AI coding assistant. Get instant market research, keyword analysis, and supplier discovery—all powered by real-time data and optimized for speed. ### Why LaunchFast MCP? - **⚡ 3x Faster** - Optimized caching and parallel processing - **🎯 Accurate** - Real-time data from Amazon and Alibaba APIs - **🧠 Intelligent** - AI-powered market grading and opportunity scoring - **🔌 Universal** - Works with Claude Desktop, Cursor, Claude Code & ChatGPT - **🛡️ Production Ready** - Rate limiting, error handling, and retry logic built-in --- ## ✨ Features ### 🔍 **Market Research** - Research 50+ Amazon products in seconds - A10-F1 market grading system (demand vs competition) - Revenue estimates, BSR tracking, and sales velocity - Filter by price, ratings, reviews, and more - Multi-marketplace support (US, UK, DE, FR, IT, ES, CA, MX, JP) ### 🎯 **Keyword Intelligence** - Deep ASIN keyword analysis (1-10 products) - Search volume, CPC, and competition metrics - **Opportunity Mining** - Find underserved, high-volume keywords - **Gap Analysis** - Discover what competitors rank for that you don't - Side-by-side ASIN comparison matrix ### 🏭 **Supplier Discovery** - Smart Alibaba supplier search with quality scoring - Top 20 suppliers ranked by trust metrics - Pricing, MOQ, certifications, and years in business - Gold Supplier & Trade Assurance filtering - Response rate and review score tracking --- ## 🚀 Quick Start ### Prerequisites - **Node.js 18+** ([Download](https://nodejs.org/)) - **Claude Desktop**, **Cursor**, or **Claude Code** installed - **LaunchFast API Key** ([Get yours](https://launchfastlegacyx.com/admin/usage-stats)) ### One-Click Installation #### Option 1: NPX (Recommended) Just add this to your AI tool's MCP config: ```json { "mcpServers": { "launchfast": { "command": "npx", "args": ["-y", "@launchfast/mcp-server"], "env": { "LAUNCHFAST_API_URL": "https://launchfastlegacyx.com", "LAUNCHFAST_API_KEY": "lf_your_key_here", "LAUNCHFAST_USER_ID": "your_user_id_here" } } } } ``` **That's it!** No git clone, no npm install. Just restart your AI tool. #### Option 2: Interactive Setup ```bash # Install globally npm install -g @launchfast/mcp-server # Run interactive setup launchfast-mcp setup # Follow the prompts to configure Claude Desktop, Cursor, or Claude Code ``` #### Option 3: Manual Installation <details> <summary>Click to expand manual setup instructions</summary> **1. Clone and Install** ```bash git clone https://github.com/launchfast/mcp-server.git cd mcp-server npm install npm run build ``` **2. Configure Your AI Tool** <details> <summary>Claude Desktop</summary> Edit: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) Or: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) ```json { "mcpServers": { "launchfast": { "command": "node", "args": ["/absolute/path/to/mcp-server/build/index.js"], "env": { "LAUNCHFAST_API_URL": "https://launchfastlegacyx.com", "LAUNCHFAST_API_KEY": "lf_your_key_here", "LAUNCHFAST_USER_ID": "your_user_id_here" } } } } ``` </details> <details> <summary>Cursor</summary> Open Cursor Settings → Features → Claude → MCP Servers Add the same config as Claude Desktop above. </details> <details> <summary>Claude Code (VS Code)</summary> Open VS Code Settings → Extensions → Claude Code → MCP Servers Add the same config as Claude Desktop above. </details> **3. Restart Your AI Tool** Look for the 🔨 hammer icon to confirm MCP tools are loaded. </details> --- ## 🛠️ Available Tools ### 1️⃣ `research_amazon_market` **Get instant market intelligence for any product keyword** ``` 🎤 Example: "Research the Amazon market for portable saunas" ``` **Input:** - `keyword` (required) - Product to research (e.g., "wireless earbuds") - `marketplace` (optional) - Amazon domain (default: "com" for US) - `limit` (optional) - Max products (default: 50) - `useCache` (optional) - Use caching for speed (default: true) - `minPrice`, `maxPrice`, `minRating` (optional) - Filters **Output:** - **Market Overview** - Grade (A10-F1), total revenue, competition level - **Top 10 Products** - ASIN, title, price, BSR, reviews, grade - **Sales Data** - Monthly units, revenue, estimated profit per unit - **Keywords** - Top ranking keywords with search volumes - **Performance** - Cache stats, processing time, provider used <details> <summary>View Example Output</summary> ``` 📊 MARKET RESEARCH: portable sauna 🎯 Market Overview ├─ Grade: A7 (Strong demand, moderate competition) ├─ Market Revenue: $2,450,000/month ├─ Competition Level: MEDIUM ├─ Recommended Entry Price: $179-$199 └─ Total Products Analyzed: 50 🏆 Top 5 Products 1. ⭐ A9 | B08N5WRWNW | HigherDOSE Infrared Sauna Blanket └─ $199 • BSR #1,234 in Health • 4.5★ (2,340 reviews) └─ Sales: 450 units/mo • Revenue: $89,550/mo • Profit/unit: ~$85 2. ⭐ A8 | B07XJ8C8F5 | REVIIV Portable Infrared Sauna └─ $169 • BSR #2,567 in Home • 4.3★ (1,890 reviews) └─ Sales: 320 units/mo • Revenue: $54,080/mo • Profit/unit: ~$72 [... more products ...] 🔑 Top Keywords ├─ "portable infrared sauna" - 12,300 vol/mo, High competition ├─ "sauna blanket infrared" - 8,900 vol/mo, Medium competition ├─ "home sauna portable" - 5,400 vol/mo, Low competition ⭐ └─ "infrared sauna pod" - 3,200 vol/mo, Low competition ⭐ ⚡ Performance └─ Processed in 3.2s (Cache: 87% hit rate, Provider: Axesso) ``` </details> --- ### 2️⃣ `research_asin_keywords` **Deep keyword analysis for Amazon products with opportunity mining** ``` 🎤 Example: "Research keywords for ASIN B08N5WRWNW with gap analysis" ``` **Input:** - `asins` (required) - Array of 1-10 ASINs (e.g., ["B08N5WRWNW"]) - `maxKeywordsPerAsin` (optional) - Max keywords per ASIN (default: 50) - `minSearchVolume` (optional) - Min monthly searches (default: 100) - `includeOpportunities` (optional) - Find low-competition gems (default: true) - `includeGapAnalysis` (optional) - Compare against competitors (default: true) **Output:** - **Per-ASIN Breakdown** - Keywords, rankings, traffic percentage - **Aggregated Keywords** - All keywords sorted by search volume - **Opportunity Keywords** - Low competition, high volume targets - **Gap Analysis** - Keywords competitors rank for but you don't - **ASIN Comparison** - Side-by-side keyword matrix <details> <summary>View Example Output</summary> ``` 🔍 KEYWORD RESEARCH: 2 ASINs 📋 ASIN: B08N5WRWNW (HigherDOSE Sauna Blanket) ├─ Total Keywords: 147 └─ Top Keywords: ├─ "infrared sauna blanket" - 14,800 vol, Rank #3, 22% traffic ├─ "sauna blanket" - 9,200 vol, Rank #5, 14% traffic └─ "portable sauna" - 12,300 vol, Rank #8, 9% traffic 📋 ASIN: B07XJ8C8F5 (REVIIV Portable Sauna) ├─ Total Keywords: 132 └─ Top Keywords: ├─ "portable infrared sauna" - 12,300 vol, Rank #2, 26% traffic ├─ "home sauna" - 8,100 vol, Rank #4, 18% traffic └─ "infrared sauna" - 18,900 vol, Rank #12, 7% traffic 💎 Opportunity Keywords (Low Competition, High Volume) 1. "home sauna portable" - 5,400 vol/mo, 32/100 competition, CPC $1.45 2. "infrared sauna therapy" - 4,200 vol/mo, 28/100 competition, CPC $1.82 3. "sauna blanket weight loss" - 3,800 vol/mo, 25/100 competition, CPC $2.10 4. "far infrared sauna" - 3,100 vol/mo, 30/100 competition, CPC $1.67 🔍 Gap Analysis (Competitors rank for, you don't) ├─ "infrared sauna benefits" - 6,700 vol/mo, Comp rank #4 ├─ "sauna at home" - 4,900 vol/mo, Comp rank #7 └─ "detox sauna blanket" - 2,800 vol/mo, Comp rank #3 📊 ASIN Comparison Matrix Keyword | B08N5... | B07XJ... ---------------------------|----------|---------- infrared sauna blanket | #3 | #15 portable infrared sauna | #8 | #2 sauna blanket | #5 | #22 home sauna portable | - | #6 ``` </details> --- ### 3️⃣ `search_alibaba_suppliers` **Find verified suppliers with quality scoring and MOQ filtering** ``` 🎤 Example: "Find Gold Suppliers for portable saunas on Alibaba" ``` **Input:** - `searchQuery` (required) - Product to source (e.g., "bluetooth speaker") - `maxResults` (optional) - Max suppliers (1-20, default: 20) - `goldSupplierOnly` (optional) - Filter Gold Suppliers (default: false) - `tradeAssuranceOnly` (optional) - Require Trade Assurance (default: false) - `minYearsInBusiness` (optional) - Min years active (default: 0) - `minMoq`, `maxMoq` (optional) - MOQ range filters - `location` (optional) - Filter by country (e.g., "China") **Output:** - **Top 20 Suppliers** - Sorted by quality score (0-100) - **Pricing & MOQ** - Unit prices, minimum order quantities - **Trust Indicators** - Gold Supplier, Trade Assurance, certifications - **Performance Metrics** - Review scores, response rate, years in business - **Quality Breakdown** - Trust, experience, pricing, and review scores - **Direct Links** - Product URLs for instant contact <details> <summary>View Example Output</summary> ``` 🏭 SUPPLIER SEARCH: portable infrared sauna 🏆 Top 5 Suppliers (by Quality Score) 1. ⭐ 94/100 | Shenzhen Wellness Tech Co., Ltd. ├─ 🏅 Gold Supplier (12 years) | ✓ Trade Assurance ├─ 📍 Guangdong, China | 💬 98% response rate ├─ ⭐ 4.9/5.0 (234 reviews) | 🎖️ ISO 9001, CE, FDA certified ├─ 💰 $45-$89/unit (MOQ: 100 units, Min order: $6,500) └─ 🔗 https://alibaba.com/product/... 2. ⭐ 89/100 | Foshan HealthCare Manufacturing ├─ 🏅 Gold Supplier (8 years) | ✓ Trade Assurance ├─ 📍 Guangdong, China | 💬 95% response rate ├─ ⭐ 4.7/5.0 (156 reviews) | 🎖️ CE, RoHS certified ├─ 💰 $52-$78/unit (MOQ: 50 units, Min order: $3,200) └─ 🔗 https://alibaba.com/product/... 3. ⭐ 87/100 | Ningbo Thermal Solutions Ltd. ├─ 🏅 Gold Supplier (15 years) | ✓ Trade Assurance ├─ 📍 Zhejiang, China | 💬 92% response rate ├─ ⭐ 4.8/5.0 (89 reviews) | 🎖️ ISO 9001, CE certified ├─ 💰 $38-$72/unit (MOQ: 200 units, Min order: $9,800) └─ 🔗 https://alibaba.com/product/... [... more suppliers ...] 📊 Quality Score Breakdown ├─ Trust Score (40%): Gold badge, Trade Assurance, certifications ├─ Experience (30%): Years in business, transaction history ├─ Pricing (20%): Competitive rates, flexible MOQ └─ Reviews (10%): Rating score, review count, response rate 💡 Recommendation: Supplier #2 (Foshan HealthCare) offers the best balance of quality (89/100), low MOQ (50 units), and competitive pricing ($52-78). 📊 Search Usage: 18/500 searches used today ``` </details> --- ## 💡 Usage Examples ### Scenario 1: Full Product Launch Research ``` 👤 You: "Help me launch a portable sauna business on Amazon" 🤖 Claude: 1. [Calls research_amazon_market with keyword="portable sauna"] → Market Grade A7, $2.5M monthly revenue, moderate competition 2. [Extracts top 3 ASINs from results] 3. [Calls research_asin_keywords with asins=[...]] → Finds 12 opportunity keywords like "home sauna portable" 4. [Calls search_alibaba_suppliers with searchQuery="portable infrared sauna"] → Identifies 5 quality suppliers at $45-89/unit, MOQ 50-200 5. Synthesizes launch plan: ✅ Market is viable with strong demand ✅ Enter at $179-199 price point ✅ Target keywords: "home sauna portable", "infrared sauna therapy" ✅ Source from Foshan HealthCare (89/100 score, $52-78/unit, MOQ 50) ✅ Estimated profit: $80-100/unit after costs ✅ Goal: 50-100 sales/month in first 3 months ``` ### Scenario 2: Competitor Analysis ``` 👤 You: "Analyze competitor ASIN B08N5WRWNW and find keyword gaps" 🤖 Claude: [Calls research_asin_keywords with includeGapAnalysis=true] 📊 Results: • Competitor ranks for 147 keywords • 23 gap keywords found (they rank, you don't) • Top gaps: "infrared sauna benefits" (6.7K vol), "detox sauna" (2.8K vol) • 8 opportunity keywords with low competition 💡 Strategy: Target gap keywords "infrared sauna benefits" and "sauna at home" in your listing and PPC campaigns for quick ranking wins. ``` ### Scenario 3: Pricing Strategy ``` 👤 You: "Research wireless earbuds under $50 with 4.5+ stars" 🤖 Claude: [Calls research_amazon_market with filters: maxPrice=50, minRating=4.5] 📊 Results: • 23 products match criteria • Price range: $24.99 - $49.99 • Sweet spot: $34.99-$39.99 (highest sales velocity) • Top seller: $36.99 with 680 units/month 💡 Recommendation: Price at $39.99 for premium positioning while staying competitive. Products at $35-40 show 2.3x higher conversion than $45+. ``` --- ## 🏗️ Architecture ``` @launchfast/mcp-server/ ├── src/ │ ├── index.ts # MCP server entry point │ ├── client/ │ │ └── launchfast-client.ts # API client with retry logic │ ├── tools/ │ │ ├── market-research.ts # Tool 1: Market research │ │ ├── asin-keywords.ts # Tool 2: Keyword intelligence │ │ └── alibaba-suppliers.ts # Tool 3: Supplier discovery │ ├── types/ │ │ └── launchfast.ts # TypeScript interfaces │ └── utils/ │ ├── logger.ts # Structured logging │ └── formatter.ts # Response formatters ├── scripts/ │ └── setup.js # Interactive setup wizard ├── install/ │ ├── claude-desktop.json # Claude Desktop config │ ├── cursor.json # Cursor config │ └── claude-code.json # Claude Code config ├── build/ # Compiled output ├── .env.example # Environment template ├── package.json └── tsconfig.json ``` ### Key Design Principles **🚀 Performance First** - Multi-layer caching (keyword→ASIN, product data) - Parallel API requests where possible - Optimized for 3x speed improvement over standard endpoints **🛡️ Production Ready** - Exponential backoff retry (1s, 2s, 4s) - Rate limit handling with 429 retry - Comprehensive error messages - Graceful degradation **🧪 Type Safe** - Full TypeScript with strict mode - Zod schema validation - Runtime type checking **🔌 Universal Compatibility** - Works with any MCP-compatible AI tool - No streaming complexity (pure JSON responses) - Simple stdio transport --- ## 📚 Documentation ### Configuration #### Environment Variables ```bash LAUNCHFAST_API_URL=https://launchfastlegacyx.com LAUNCHFAST_API_KEY=lf_your_64_char_hex_key LAUNCHFAST_USER_ID=your_uuid_here ``` Get your credentials from: [LaunchFast Admin Dashboard](https://launchfastlegacyx.com/admin/usage-stats) #### Rate Limits - **Global Rate Limit**: 20 requests/minute across all MCP users - **Market Research**: Cached results recommended (useCache: true) - **Keyword Research**: Session-based caching - **Supplier Search**: Usage tracking in response (`searchesUsed`, `searchesRemaining`) All responses include rate limit headers: ``` X-RateLimit-Limit: 20 X-RateLimit-Remaining: 15 X-RateLimit-Reset: 1704067200 ``` ### Development ```bash # Install dependencies npm install # Run in development mode npm run dev # Build for production npm run build # Inspect MCP tool schemas npm run inspect # Run interactive setup node scripts/setup.js ``` ### Testing ```bash # Test market research curl -X POST https://launchfastlegacyx.com/api/products/research \ -H "X-LaunchFast-API-Key: lf_your_key" \ -H "Content-Type: application/json" \ -d '{"keyword": "test product", "limit": 5}' # Test keyword research curl -X POST https://launchfastlegacyx.com/api/keywords/research \ -H "X-LaunchFast-API-Key: lf_your_key" \ -H "Content-Type: application/json" \ -d '{"asins": ["B08N5WRWNW"]}' # Test supplier search curl -X POST https://launchfastlegacyx.com/api/suppliers/search \ -H "X-LaunchFast-API-Key: lf_your_key" \ -H "Content-Type: application/json" \ -d '{"keyword": "bluetooth speaker"}' ``` --- ## 🐛 Troubleshooting <details> <summary>🔨 Tools not appearing in Claude</summary> 1. **Verify config location**: ```bash # macOS cat ~/Library/Application\ Support/Claude/claude_desktop_config.json # Windows type %APPDATA%\Claude\claude_desktop_config.json ``` 2. **Check build exists**: ```bash ls -la build/index.js # If missing: npm run build ``` 3. **Test server directly**: ```bash npm run inspect # Should list 3 tools without errors ``` 4. **Check Claude logs**: ```bash # macOS tail -f ~/Library/Logs/Claude/mcp*.log # Windows type %APPDATA%\Claude\logs\mcp*.log ``` </details> <details> <summary>🔑 Authentication errors</summary> **401 Unauthorized** - Check `LAUNCHFAST_API_KEY` starts with `lf_` - Verify key in admin dashboard: [LaunchFast Admin](https://launchfastlegacyx.com/admin/usage-stats) **403 Forbidden** - Verify `LAUNCHFAST_USER_ID` matches your account - Check key is not disabled in admin dashboard **429 Too Many Requests** - Global rate limit: 20 req/min across all users - Check `Retry-After` header for wait time - Enable caching with `useCache: true` for market research </details> <details> <summary>⚠️ API errors</summary> **"Cannot read properties of undefined"** - API response format may have changed - Check API docs: [LaunchFast API](https://launchfastlegacyx.com/api/docs) - Report issue: [GitHub Issues](https://github.com/launchfast/mcp-server/issues) **500 Server Error** - Automatic retry will attempt 3 times (1s, 2s, 4s backoff) - If persists, check API status **Timeout errors** - Default timeout: 30 seconds - Try with `useCache: true` for faster response - Reduce `limit` parameter for market research </details> <details> <summary>🔧 Installation issues</summary> **"Missing required environment variables"** ```bash # Create .env file cat > .env << EOF LAUNCHFAST_API_URL=https://launchfastlegacyx.com LAUNCHFAST_API_KEY=lf_your_key_here LAUNCHFAST_USER_ID=your_user_id_here EOF ``` **"Node version too old"** ```bash node --version # Must be v18.0.0+ # Upgrade: https://nodejs.org/ ``` **"Cannot find module '@modelcontextprotocol/sdk'"** ```bash rm -rf node_modules package-lock.json npm install npm run build ``` </details> --- ## 🤝 Contributing We love contributions! Here's how to get started: 1. **Fork** the repository 2. **Clone** your fork: `git clone https://github.com/YOUR_USERNAME/mcp-server.git` 3. **Create** a branch: `git checkout -b feature/amazing-feature` 4. **Make** your changes 5. **Test** thoroughly: `npm run dev` 6. **Commit**: `git commit -m 'Add amazing feature'` 7. **Push**: `git push origin feature/amazing-feature` 8. **Open** a Pull Request ### Development Guidelines - ✅ Use TypeScript strict mode - ✅ Add JSDoc comments for public functions - ✅ Include error handling (try/catch) - ✅ Follow existing code style (2 spaces, single quotes) - ✅ Test with real API calls before submitting - ✅ Update README if adding features ### Good First Issues - [ ] Add support for more Amazon marketplaces - [ ] Improve error messages with actionable suggestions - [ ] Add progress indicators for long-running requests - [ ] Create video tutorial for installation - [ ] Add unit tests for formatter functions --- ## 📄 License MIT License - see [LICENSE](LICENSE) file for details. You are free to use, modify, and distribute this software for commercial or non-commercial purposes. --- ## 🙏 Acknowledgments - **[Anthropic](https://anthropic.com)** - For Claude AI and the Model Context Protocol - **[LaunchFast](https://launchfastlegacyx.com)** - For the powerful e-commerce research APIs - **[MCP Community](https://modelcontextprotocol.io)** - For tools, docs, and inspiration --- ## 📞 Support & Community - 📚 **Documentation**: [GitHub Wiki](https://github.com/launchfast/mcp-server/wiki) - 💬 **Discussions**: [GitHub Discussions](https://github.com/launchfast/mcp-server/discussions) - 🐛 **Bug Reports**: [GitHub Issues](https://github.com/launchfast/mcp-server/issues) - 📧 **Email**: support@launchfastlegacy.com - 🌐 **Website**: [launchfastlegacyx.com](https://launchfastlegacyx.com) --- ## 🗺️ Roadmap ### Q1 2025 - [ ] Session management for research history - [ ] Export results to CSV/Excel/JSON - [ ] Bulk ASIN analysis (50+ products) - [ ] Product tracking and price alerts ### Q2 2025 - [ ] eBay marketplace support - [ ] Walmart marketplace support - [ ] Web dashboard for visualization - [ ] Slack/Discord notifications ### Q3 2025 - [ ] Competitive intelligence reports - [ ] AI-powered product ideation - [ ] Listing optimization suggestions - [ ] PPC campaign builder **Vote on features**: [Feature Requests](https://github.com/launchfast/mcp-server/discussions/categories/feature-requests) --- ## 🌟 Star History If you find this project useful, please consider giving it a ⭐ on GitHub! --- <div align="center"> **Built with ❤️ by the LaunchFast team for Amazon sellers and product researchers** [Get Started](#-quick-start) • [View Demo](#-usage-examples) • [Read Docs](#-documentation) • [Join Community](#-support--community) </div>