MarsSignal MCP Server

🚀 AI Assistant integration for eSIM management - Connect your favorite AI assistant (ChatGPT, Claude, DeepSeek, etc.) to MarsSignal's eSIM services through the Model Context Protocol (MCP).

🚀 AI 助手集成 eSIM 管理 - 通过模型上下文协议 (MCP) 将您喜爱的 AI 助手（ChatGPT、Claude、DeepSeek 等）连接到 MarsSignal 的 eSIM 服务。

✨ Features | 功能特性

English

• 🛒 Smart eSIM Purchase - AI-powered product recommendations and one-click purchasing
• 🔄 Automatic Renewal - Intelligent renewal management with expiration alerts
• 📊 Usage Analytics - Real-time data usage monitoring and trend analysis
• 📱 eSIM Management - Complete lifecycle management of your eSIM cards
• 🎯 Personalized Recommendations - AI-driven suggestions based on travel patterns
• 🔒 Secure Authentication - Dual verification with MarsID + API Key

中文

• 🛒 智能 eSIM 购买 - AI 驱动的产品推荐和一键购买
• 🔄 自动续费 - 智能续费管理和到期提醒
• 📊 使用分析 - 实时数据使用监控和趋势分析
• 📱 eSIM 管理 - eSIM 卡的完整生命周期管理
• 🎯 个性化推荐 - 基于旅行模式的 AI 驱动建议
• 🔒 安全认证 - MarsID + API Key 双重验证

🚀 Quick Start

1. Get Your Credentials

Visit MarsSignal Dashboard to:

1. Generate your MarsID (format: M0123456789)
2. Create your API Key (format: mcp_live_...)

2. Install the MCP Server

npm install -g marssignal-mcp-server

3. Choose Your Integration Mode

🖥️ Stdio Mode (ChatGPT Desktop / Claude Desktop)

Add to your AI assistant's MCP configuration:

{
  "mcpServers": {
    "marssignal-esim": {
      "command": "npx",
      "args": ["marssignal-mcp-server"],
      "env": {
        "MARS_ID": "M0123456789",
        "API_KEY": "mcp_live_your_api_key_here"
      }
    }
  }
}

🌐 HTTP Mode (Dify / Web-based AI)

Start the HTTP server:

# Start HTTP server
npx marssignal-mcp-server --http --port 3001

# Or for development
npm run dev:http

Configure in Dify or other web-based AI platforms:

{
  "mcp_server": {
    "name": "marssignal-esim",
    "transport": "http",
    "url": "http://localhost:3001",
    "endpoints": {
      "sse": "/sse",
      "message": "/message",
      "health": "/health"
    }
  }
}

Each tool call requires:

• marsId: Your MarsSignal ID (M0123456789)
• apiKey: Your API Key (mcp_live_...)

4. Start Using!

Now you can ask your AI assistant:

• "I'm traveling to Japan for 7 days, recommend an eSIM plan"
• "Check my eSIM data usage"
• "Renew my expiring eSIM"
• "Show me my recent orders"

🛠️ Configuration

Environment Variables | 环境变量

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | MARS_ID | ✅ | Your MarsSignal MarsID | M0123456789 | | API_KEY | ✅ | Your MarsSignal API Key | mcp_live_abc123... | | DEBUG | ❌ | Enable debug logging | false |

Configuration File

Create a .env file in your project:

# Required credentials | 必需凭证
MARS_ID=M0123456789
API_KEY=mcp_live_your_64_character_api_key_here

# Optional: Debug mode (for troubleshooting only) | 可选：调试模式（仅用于故障排除）
DEBUG=false

🔧 Available Tools

🛒 purchase_esim

Purchase an eSIM plan based on travel requirements.

Parameters:

• destination (string) - Travel destination
• duration (number) - Trip duration in days
• dataUsage (enum) - Expected usage: light, medium, heavy
• budget (number, optional) - Budget limit in USD
• autoSelect (boolean, optional) - Auto-select best plan (default: true)

🔄 renew_esim

Renew an existing eSIM or extend its validity.

Parameters:

• esimId / orderNumber / iccid - eSIM identifier
• renewalType (enum) - Renewal type: auto, manual, upgrade
• newPlan (string, optional) - New plan code for manual/upgrade
• autoRenew (boolean, optional) - Enable automatic renewal

📊 get_esim_usage

Check data usage and status of eSIM cards.

Parameters:

• esimId / orderNumber / iccid (optional) - Specific eSIM to check
• includeHistory (boolean) - Include usage history
• analysisType (enum) - Analysis type: summary, detailed, trend

📱 list_esims

List all eSIM cards with their status and details.

Parameters:

• status (enum) - Filter by status: all, active, expired, pending
• includeExpired (boolean) - Include expired eSIMs
• limit (number) - Maximum number of results

🎯 get_product_recommendations

Get personalized eSIM product recommendations.

Parameters:

• destination (string) - Travel destination
• duration (number) - Trip duration in days
• dataUsage (enum) - Expected usage level
• budget (number, optional) - Budget limit
• features (string, optional) - Required features (comma-separated)
• limit (number) - Number of recommendations

📋 get_order_status

Check the status of orders and manage them.

Parameters:

• orderNumber (string, optional) - Specific order to check
• status (enum) - Filter by status: all, pending, paid, failed, cancelled
• limit (number) - Maximum number of results

❌ cancel_order

Cancel a pending order.

Parameters:

• orderNumber (string) - Order number to cancel
• reason (string, optional) - Cancellation reason

🤖 AI Assistant Examples

Smart Purchase

User: "I'm going to Tokyo for 10 days, need an eSIM with good data for streaming"

AI: I'll help you find the perfect eSIM for your Tokyo trip! Let me get recommendations for 10 days with heavy data usage.

[Calls purchase_esim with destination="Tokyo", duration=10, dataUsage="heavy", autoSelect=true]

Great! I found the perfect plan for your Tokyo trip:
- Product: Japan Unlimited 10-Day eSIM
- Price: $24.99
- Data: Unlimited high-speed data
- Validity: 10 days
- Score: 95/100 (Perfect match for streaming)

Your order #MCP1234567890 has been created. Please complete payment at: [payment_url]

Usage Monitoring

User: "How much data have I used on my Japan eSIM?"

AI: Let me check your eSIM usage data.

[Calls get_esim_usage with analysisType="detailed"]

Here's your Japan eSIM usage:
- Total Data: 20GB
- Used: 12.5GB (62.5%)
- Remaining: 7.5GB
- Daily Average: 1.8GB/day
- Trend: Medium usage
- Estimated depletion: 4 days remaining

You're using data at a moderate pace. Your current usage should last until the end of your trip!

🔒 Security

• Dual Authentication: Requires both MarsID and API Key
• Encrypted Communication: All API calls use HTTPS
• No Data Storage: Server doesn't store any user data locally
• Revokable Access: API Keys can be regenerated anytime

🆘 Troubleshooting

Common Issues

"Configuration Error: MARS_ID format is invalid"

• Ensure your MarsID follows the format M followed by 10 digits
• Get your MarsID from the dashboard

"API Key format is invalid"

• API Key should start with mcp_live_ followed by 64 hex characters
• Generate a new API Key if yours doesn't match this format

"Authentication failed"

• Verify both MarsID and API Key are correct
• Check if your API Key has expired or been revoked

Debug Mode

Enable debug logging to see detailed API communication:

DEBUG=true npx marssignal-mcp-server

📞 Support | 技术支持

English

• 🌐 Website: marssignal.com
• 📧 Email: [email protected]
• 📚 Documentation: marssignal.com/mcp

中文

• 🌐 官网: marssignal.com
• 📧 邮箱: [email protected]
• 📚 文档: marssignal.com/mcp

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the MarsSignal Team

Connecting the world, one eSIM at a time 🌍📡