omnigapai/android-sms-gateway-mcp

Android SMS Gateway MCP Server

A microservice that integrates with Android SMS Gateway app to provide SMS sending/receiving capabilities with AI-powered message processing.

Features

• Send SMS messages with coach name formatting
• Receive SMS via webhooks or polling
• LLM processing for intent detection and urgency classification
• Message transfer between coaches
• Real-time gateway health monitoring

Prerequisites

1. Android SMS Gateway App

   • Install from: https://github.com/capcom6/android-sms-gateway
   • Configure on your Android device
   • Note the gateway URL (usually your phone's IP:8080)

2. Node.js 18+

3. OpenAI API Key (optional, for AI features)

Setup

1. Install dependencies:

npm install

2. Create .env file:

cp .env.example .env

3. Configure .env:

# Your Android device's gateway URL
GATEWAY_URL=http://192.168.1.100:8080
GATEWAY_USERNAME=admin
GATEWAY_PASSWORD=your_password

# For AI message processing
OPENAI_API_KEY=sk-...

# Server port
PORT=3005

4. Start the server:

npm start

API Endpoints

Send SMS

POST /api/sms/send
{
  "to": "+1234567890",
  "message": "Hello!",
  "coachLastName": "Smith"
}

Receive Messages

GET /api/sms/received?limit=50&processed=true

Transfer Message

POST /api/sms/transfer
{
  "messageId": "123",
  "toCoachPhone": "+1234567890",
  "toCoachLastName": "Johnson"
}

Health Check

GET /health
GET /api/gateway/status

Webhook Configuration

Configure your Android SMS Gateway to send webhooks to:

https://your-server.com/webhook/sms-received

Deployment to Railway

1. Push to GitHub
2. Connect repo to Railway
3. Set environment variables in Railway dashboard
4. Deploy!

Message Flow

Android Phone → SMS Gateway App → MCP Server → LLM Processing → Coach Dashboard

LLM Features

When OPENAI_API_KEY is configured, incoming messages are analyzed for:

• Intent (registration, payment, scheduling, etc.)
• Urgency level (high, medium, low)
• Suggested responses
• Key entities extraction
• Recommended coach actions

Troubleshooting

Gateway not connecting

• Check GATEWAY_URL is correct
• Ensure Android device is on same network
• Verify username/password

Messages not receiving

• Enable polling in .env: ENABLE_POLLING=true
• Check webhook configuration in Android app
• Verify port forwarding if using external access

LLM not processing

• Verify OPENAI_API_KEY is valid
• Check API quota/limits
• Review server logs for errors