Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/harshaneigapula/ios_mcp
cd ios_mcp
pip install -r requirements.txtRegister it in Claude Code
claude mcp add ios-mcp -- python /absolute/path/to/ios_mcp/src/server.pyReplace any placeholder paths in the command with the real path on your machine.
Make your agent remember this setup
ios-mcp's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Connects to iPhone via USB using libimobiledevice
- Semantic search using ChromaDB for natural language queries
- Exact metadata filtering for precise file management
- Incremental scanning with cached results for instant querying
- Advanced aggregation pipelines for complex data analysis
Tools 14
list_connected_devicesLists UDIDs of connected iOS devices.scan_and_cache_photosMounts the device, scans DCIM, and indexes metadata into the Vector DB.search_filesSemantic search using natural language for photos based on Photo Metadata.filter_filesExact metadata filtering.count_filesCount files matching semantic or exact criteria.group_filesGroup files by a field and return counts.run_advanced_queryComplex query with sorting, pagination, and projection.run_aggregation_pipelineMulti-stage data processing pipeline (MongoDB style).get_metadata_keysLists all available metadata fields.find_similar_metadata_keysFinds valid keys similar to a typo.read_imageReads and resizes an image, returning base64 data.copy_files_to_localCopies files to a local directory, with optional renaming.mount_device_for_file_accessManually mount the device.check_db_statusCheck database connection health.Try it
Original README from harshaneigapula/ios_mcp
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](https://drive.google.com/file/d/1yyqCKYXskhf4JLdMTkgvbPJ6gCqacOG3/view?usp=sharing)
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
📢 Social Media Post
Prerequisites
- macOS: This tool relies on macOS-specific tools for iOS connectivity.
- System Tools:
brew install libimobiledevice ifuse exiftool - Python 3.10+
Installation
Clone the repository:
git clone https://github.com/harshaneigapula/ios_mcp cd ios_mcpInstall 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:
- Go to Settings > MCP Servers.
- Add a new server:
- Name:
ios-mcp - Command:
python - Args:
/absolute/path/to/ios_mcp/src/server.py
- Name:
Available Tools
| Tool | Description |
|---|---|
list_connected_devices |
Lists UDIDs of connected iOS devices. |
scan_and_cache_photos |
Mounts the device, scans DCIM, and indexes metadata into the Vector DB. |
search_files |
Semantic search using natural language for photos based on Photo Metadata (e.g., "Photos of Apple 12 taken during 2024"). |
filter_files |
Exact metadata filtering (e.g., {"Flash": true}). |
count_files |
Count files matching semantic or exact criteria. |
group_files |
Group files by a field and return counts (e.g., group by "Model"). |
run_advanced_query |
Complex query with sorting, pagination, and projection. |
run_aggregation_pipeline |
Multi-stage data processing pipeline (MongoDB style). |
get_metadata_keys |
Lists all available metadata fields (columns). |
find_similar_metadata_keys |
Finds valid keys similar to a typo. |
read_image |
Reads and resizes an image, returning base64 data. |
copy_files_to_local |
Copies files to a local directory, with optional renaming. |
mount_device_for_file_access |
Manually mount the device. |
check_db_status |
Check database connection health. |
🧠 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}