batteryshark/mcp-findmy

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

pip install -r requirements.txt
# or if using uv:
uv sync

Build

uv build

Usage

Running the Server

# 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

"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.