rexrk/ScoutlyMCP

ScoutlyMCP

ScoutlyMCP is a Model Context Protocol (MCP) server that enables AI assistants to retrieve SMS messages from Android devices via ADB (Android Debug Bridge). This tool bridges your Android SMS inbox with AI assistants, allowing them to read and analyze your text messages when needed.

Features

• 🔍 SMS Retrieval: Fetch latest SMS messages from Android devices
• 🤖 MCP Integration: Compatible with MCP-enabled AI assistants
• 📱 ADB-based: Uses Android Debug Bridge for secure device communication
• ⚡ Fast Processing: Efficiently parses and formats SMS data
• 📊 Structured Output: Returns well-formatted JSON data with timestamps

Prerequisites

• Python 3.12 or higher
• Android Debug Bridge (ADB) installed and accessible in PATH
• Android device with USB debugging enabled
• Connected Android device via USB

Installing ADB

Ubuntu/Debian:

sudo apt install android-tools-adb

macOS:

brew install android-platform-tools

Windows: Download from Android SDK Platform Tools

Installation

1. Clone the repository:

   git clone https://github.com/rexrk/ScoutlyMCP.git
   cd ScoutlyMCP
   

2. Install dependencies:

   pip install -e .
   

Setup

Android Device Configuration

1. Enable Developer Options:

   • Go to Settings → About Phone
   • Tap "Build Number" 7 times

2. Enable USB Debugging:

   • Go to Settings → Developer Options
   • Enable "USB Debugging"

3. Connect and Verify:

   adb devices
   

   Your device should appear in the list.

Usage

Standalone Usage

Run the SMS parser directly:

python src/message_parser.py

As MCP Server

Start the MCP server:

python src/main.py

The server will run in stdio mode, ready to receive MCP requests.

MCP Tool Usage

The server exposes one tool:

• sms_message: Retrieve latest SMS messages
  • Parameter: limit (optional, default: 5) - Number of messages to retrieve

Example Output

[
  {
    "id": "123",
    "address": "+1234567890",
    "date": "2024-01-15T10:30:45.000Z",
    "body": "Hello! This is a sample SMS message."
  },
  {
    "id": "122",
    "address": "contact@example.com",
    "date": "2024-01-15T09:15:30.000Z",
    "body": "Another message example with multiple lines\nThis continues on the next line."
  }
]

Integration with AI Assistants

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "sms-reader": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/ScoutlyMCP",
        "-m",
        "src.main"
      ]
    }
  }
}

Project Structure

ScoutlyMCP/
├── src/
│   ├── __init__.py
│   ├── main.py              # MCP server entry point
│   └── message_parser.py    # SMS parsing logic
├── pyproject.toml          # Project dependencies
├── README.md
└── uv.lock                # Lock file for dependencies

Development

Running Tests

# Test SMS parsing functionality
python src/message_parser.py

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Security Considerations

• Device Access: This tool requires ADB access to your Android device
• SMS Privacy: Only use with trusted AI assistants and secure environments
• Network Security: Ensure your development environment is secure
• Permissions: The tool only reads SMS data, it cannot send messages

Troubleshooting

Common Issues

ADB not found:

Error: ADB not found. Please ensure it is installed and in your system's PATH.

→ Install ADB and add to PATH

Device not connected:

Error executing ADB command

→ Check USB connection and enable USB debugging

No SMS data:

• Verify device has SMS messages in inbox
• Check ADB permissions on device
• Ensure device is unlocked during operation

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Built using FastMCP
• Android Debug Bridge by Google
• Model Context Protocol specification

Support

If you encounter any issues or have questions:

• Open an Issue
• Check existing Discussions

Note: Remember to replace yourusername with your actual GitHub username when uploading to GitHub.