README.md•2.7 kB
# Apple Find My MCP Server
An MCP (Model Context Protocol) server that provides access to Apple's Find My network for device tracking and management.
## Overview
This server allows you to interact with your Apple devices through the Find My network, providing location tracking, battery status, and device information via MCP-compatible tools.
## Features
### Device Management
- **List Devices**: Retrieve all devices associated with your Apple account
- **Device Info**: Get detailed information including location, battery level, and status for specific devices
- **Caching**: 5-minute cache for improved performance and reduced API calls
### Administration
- **Cache Management**: Clear caches, refresh data, or reset authentication
- **Credential Management**: Securely store and manage Apple ID credentials
- **Authentication**: Interactive Apple ID authentication with secure credential storage
## Tools
### Device Tools
- `list_devices()` - List all Find My devices with basic information
- `get_device_info(discovery_id)` - Get comprehensive details for a specific device
### Admin Tools
- `clear_stored_credentials()` - Remove stored Apple ID and password from secure storage
- `refresh_cache()` - Clear data cache and force fresh data retrieval
## Installation
### Prerequisites
- Python 3.11+
- Apple ID with Find My enabled
### Install Dependencies
```bash
pip install -r requirements.txt
# or if using uv:
uv sync
```
### Build
```bash
uv build
```
## Usage
### Running the Server
```bash
# Using uv
uv run server
# Or directly
python server.py
```
### Configuration
- **HOST**: Server host (default: 127.0.0.1)
- **PORT**: Server port (optional, defaults to auto-assigned)
### MCP Configuration Example
```json
"findmy-server": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/path/to/findmy-server",
"run",
"server"
]
},
```
## Authentication
The server uses interactive authentication for your Apple ID. On first use:
1. Provide your Apple ID email when prompted
2. Enter your password (stored securely using keyring)
3. Complete 2FA if required
Credentials are stored securely and reused for subsequent requests.
## Dependencies
- `fastmcp>=2.11.3` - MCP server framework
- `pyicloud>=2.0.2` - Apple iCloud/Find My API client
- `keyring>=25.6.0` - Secure credential storage
## Security
- Credentials are stored securely using system keyring
- Authentication state is cached per session
- Data is cached for 5 minutes to minimize API calls
- No sensitive data is logged or stored permanently
## License
This project is provided as-is for personal use with Apple's Find My service.