# ScoutlyMCP

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:**
```bash
sudo apt install android-tools-adb
```

**macOS:**
```bash
brew install android-platform-tools
```

**Windows:**
Download from [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools)

## Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/rexrk/ScoutlyMCP.git
   cd ScoutlyMCP
   ```

2. **Install dependencies:**
   ```bash
   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:**
   ```bash
   adb devices
   ```
   Your device should appear in the list.

## Usage

### Standalone Usage

Run the SMS parser directly:
```bash
python src/message_parser.py
```

### As MCP Server

Start the MCP server:
```bash
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

```json
[
  {
    "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:
```json
{
  "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

```bash
# 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 [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built using [FastMCP](https://github.com/jlowin/fastmcp)
- Android Debug Bridge by Google
- Model Context Protocol specification

## Support

If you encounter any issues or have questions:
- Open an [Issue](https://github.com/yourusername/ScoutlyMCP/issues)
- Check existing [Discussions](https://github.com/yourusername/ScoutlyMCP/discussions)

---

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