title: iOS MCP Server emoji: 📱 colorFrom: blue colorTo: purple sdk: gradio sdk_version: 6.0.1 app_file: app.py pinned: false tags:

• building-mcp-track-consumer
• mcp
• ios
• agent license: mit short_description: MCP Server to connect to IOS Devices locally

iOS MCP Server

A Model Context Protocol (MCP) server that allows Large Language Models (LLMs) to access, scan, and search photos on a connected iOS device.

📺 Watch the Demo Video

Features

• Device Access: Connects to iPhone via USB using libimobiledevice.
• Smart File Copying: Organize and copy files to your computer with auto-renaming based on metadata.
• Semantic Search: Uses ChromaDB (Vector Database) to enable natural language search (e.g., "Find photos of my trip to Paris").
• Exact Filtering: Supports precise metadata filtering (e.g., {"Model": "iPhone 12"}).
• Incremental Scanning: "Execute once, query many" architecture. Scans are cached, so subsequent queries are instant.
• Introspection: Tools to discover available metadata fields and fix typos.

🏆 MCP Hackathon Submission

Track: building-mcp-track-consumer

👥 Team Members

• harshaneigapula

📢 Social Media Post

• LinkedIn Submission Post

Prerequisites

1. macOS: This tool relies on macOS-specific tools for iOS connectivity.
2. System Tools:

   brew install libimobiledevice ifuse exiftool
   

3. Python 3.10+

Installation

1. Clone the repository:

   git clone https://github.com/harshaneigapula/ios_mcp
   cd ios_mcp
   

2. Install Python dependencies:

   pip install -r requirements.txt
   

Usage

1. Connect your iPhone

Connect your iPhone via USB and ensure you have "Trusted" the computer on the device.

2. Start the MCP Server

You can run the server directly:

mcp run src/server.py

3. Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ios-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/ios_mcp/src/server.py"]
    }
  }
}

Perplexity

If using the Perplexity Desktop app or MCP integration:

1. Go to Settings > MCP Servers.
2. Add a new server:
   • Name: ios-mcp
   • Command: python
   • Args: /absolute/path/to/ios_mcp/src/server.py

Available Tools

🧠 Advanced Data Analysis

The server supports powerful data analysis capabilities modeled after MongoDB.

Aggregation Pipeline (run_aggregation_pipeline)

Process data through a multi-stage pipeline. Supported stages: $match, $group, $project, $sort, $limit, $count.

Example: Find camera models with average ISO > 200

[
  {"$match": {"Make": "Apple"}},
  {"$group": {
    "_id": "$Model", 
    "avg_iso": {"$avg": "$ISO"},
    "count": {"$sum": 1}
  }},
  {"$match": {"avg_iso": {"$gt": 200}}},
  {"$sort": {"count": -1}}
]

Advanced Querying (run_advanced_query)

Perform complex queries with sorting and pagination.

Example: Get the 10 most recent photos

{
  "where": {"MIMEType": "image/jpeg"},
  "sort_by": "CreationDate",
  "sort_order": "desc",
  "limit": 10
}

Grouping (group_files)

Quickly see the distribution of your files.

• Input: field="Model"
• Output: {"iPhone 12": 150, "iPhone 13 Pro": 42}

📂 File Management

Copying & Organizing Files (copy_files_to_local)

The copy_files_to_local tool allows you to copy files from the iOS device to your local machine.

Key Feature: Renaming for Organization You can provide a list of new_filenames matching the source files. This is powerful when combined with metadata. For example, you can rename files based on their creation date or location to organize them automatically.

Example: Copy and Rename

# Conceptual example of what the LLM does
source_files = ["/tmp/iphone/DCIM/IMG_001.JPG", "/tmp/iphone/DCIM/IMG_002.JPG"]
new_names = ["2024-01-01_Paris_001.jpg", "2024-01-01_Paris_002.jpg"]

copy_files_to_local(source_paths=source_files, destination_folder="/Users/me/Photos", new_filenames=new_names)

🛠️ Utility Tools

• read_image: Reads an image file (JPG, HEIC, etc.) from the device, resizes it (max 1024px), and returns a base64 encoded string. Useful for passing images to Vision-capable LLMs. (Most of the LLMs don't support image input as of now. More testing is needed here.)
• mount_device_for_file_access: Manually mounts the device if you need to perform operations outside the standard scan flow.

Testing

Local Test (No MCP)

Run the local test script to verify device connectivity and database operations without the MCP layer:

python3 tests/test_local.py

LLM Test

Once connected to an LLM:

1. Scan: "Scan my iPhone for photos."
2. Search: "Find photos taken in 2024."
3. Introspect: "What metadata fields are available?"