MCP Photo Location

MCP照片定位服务器

从照片文件中提取、分析和管理GPS位置信息的模型上下文协议（MCP）服务器。

🎯 为什么是MCP？与LLM的区别

一般LLM无法：

• 直接从物理文件系统读取EXIF数据
• 正确解析二进制映像文件的元数据
• 修改源文件（删除/掩蔽GPS信息）
• 批量处理文件夹中的数百个文件
• 用地理击剑算法计算距离
• 与外部API（反向编码）集成

此MCP服务器提供：

• ✅ 实际文件访问：直接处理本地文件系统中的照片
• ✅ 正确的EXIF解析：使用piexif库精确提取GPS数据
• ✅ 修改源文件：删除GPS信息以保护隐私
• ✅ 大规模批处理：高效处理数百至数千张照片
• ✅ 数学准确性：用Haversine公式计算距离（误差\=2.13.1`：MCP服务器框架
• mcp>=1.22.0：Model Context协议库
• Pillow>=10.0.0：图像文件处理
• piexif>=1.1.3：解析/修改EXIF数据
• httpx>=0.28.0：HTTP客户端（反向编码API）
• uvicorn>=0.38.0：ASGI服务器

🔌 MCP服务器端点设置

复制以下设置并将其粘贴到MCP客户端（Cursor、Claude Desktop等）设置文件中：

使用虚拟环境Python（推荐）

{
  "mcpServers": {
    "photo-location": {
      "command": "C:\\AIproject\\mcp-photo-location\\mcp-photo-location\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\AIproject\\mcp-photo-location\\mcp-photo-location\\server.py"
      ],
      "cwd": "C:\\AIproject\\mcp-photo-location\\mcp-photo-location"
    }
  }
}

使用系统python

{
  "mcpServers": {
    "photo-location": {
      "command": "python",
      "args": [
        "C:\\AIproject\\mcp-photo-location\\mcp-photo-location\\server.py"
      ],
      "cwd": "C:\\AIproject\\mcp-photo-location\\mcp-photo-location"
    }
  }
}

设置文件位置：

• 光标: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• 克劳德桌面版: %APPDATA%\Claude\claude_desktop_config.json

⚠️ 请参见：如果项目路径不同 C:\\AIproject\\mcp-photo-location\\mcp-photo-location 请将部分更改为实际项目路径。

🛠️ 可用工具（MCP Tools）

所有工具 物理文件系统在中工作， 二进制EXIF数据直接解析。

1. get_photo_location

从单个照片文件中提取GPS位置信息。

技术特性：

• 使用piexif库直接解析EXIF数据
• 将GPS纬度/经度准确转换为十进制坐标
• 使用OpenStreetMap Nominam API进行逆向编码（中文地址）
• 自动生成Google Maps链接

参数：

• image_path （string）：图像文件路径

返回值：

• JSON格式的位置信息（纬度、经度、高度、地址、Google Maps链接）

与LLM的区别： LLM无法读取文件，但该工具从实际文件中提取EXIF元数据。

2. get_photo_location_from_base64

从Base64编码的图像数据中提取GPS位置信息。

技术特性：

• Base64解码后创建临时文件
• 提取EXIF数据后自动清理临时文件
• 支持数据URI格式（data:image/jpeg；base64，…）

参数：

• image_base64 （string）：Base64编码的图像数据
• image_format （string）：图像格式（“jpg”、“png”、“tiff”），默认值：“jpg”

返回值：

• JSON格式的位置信息（纬度、经度、地址、Google Maps链接）

与LLM的区别： LLM只能“查看”图像内容，但该工具解析实际的EXIF元数据。

3. batch_get_photo_locations

从目录中的所有照片文件中批量提取GPS位置信息。

技术特性：

• 使用Path.iterdir（）遍历目录
• 支持的格式过滤（.jpg、.jpeg、.png、.tiff、.tif）
• 每个文件独立解析EXIF数据
• 优化批量文件处理

参数：

• directory_path （string）：图像文件所在的目录路径

返回值：

• JSON格式的位置信息列表（包括每张照片的文件名、路径、位置和地址）

与LLM的区别： LLM无法识别文件夹结构，但此工具将在实际目录中导航。

4. geofence_photos

地理击剑功能：以特定位置为中心过滤半径内/外的照片。

技术特性：

• Haversine公式 使用：精确计算考虑地球曲率的距离
• 距离计算误差\<0.5%（基于球面三角法）
• 实时计算每张照片的GPS坐标和中心点之间的距离
• 支持半径内（inside）/外（outside）过滤

什么是Geofencing？

• 定义特定地理边界（geographical boundary）的技术
• 判断距离指定中心点半径内还是外
• 例如：“距离首尔市厅5公里半径内的照片”、“房子周围1公里内的照片”等

与LLM的区别： LLM无法进行数学距离计算，但该工具可执行精确的地球坐标系计算。

参数：

• directory_path （string）：图像文件所在的目录路径
• center_latitude （float）：中心点的纬度
• center_longitude （float）：中心点的经度
• radius_km （float）：半径（公里）
• filter_mode （string）：“inside”（半径内）或“outside”（半径外），默认值：“inside”

返回值：

• 以JSON格式过滤的照片列表（包括每张照片中心点的距离）

示例：

# 서울시청(37.5665, 126.9780)에서 5km 반경 내 사진 찾기
geofence_photos(
    "C:/Users/username/Pictures",
    center_latitude=37.5665,
    center_longitude=126.9780,
    radius_km=5.0,
    filter_mode="inside"
)

5. remove_gps_from_photo

从照片文件中删除GPS位置信息。（仅在用户明确要求时运行）

技术特性：

• 使用piexif加载EXIF数据
• 选择性地删除GPS部分（保留其他EXIF数据）
• 使用Pillow重新保存图像（无质量损失）
• 自动创建原始文件备份（.bak文件）
• 可指定输出路径（修改源文件或创建新文件）

注意： 此功能允许您修改源文件。默认情况下，创建备份。

与LLM的区别： LLM无法修改文件，但该工具会处理实际二进制文件中的EXIF数据。

参数：

• image_path （string）：图像文件路径
• create_backup （bool）：如果为True，请使用扩展名.bak备份原始文件，默认值：True
• output_path （string，optional）：保存为新文件的路径（如果为None，则修改原始文件）

返回值：

• JSON格式的操作结果

示例：

# GPS 정보 제거 (백업 생성)
remove_gps_from_photo("C:/Users/username/Pictures/photo.jpg", create_backup=True)

# 새 파일로 저장
remove_gps_from_photo(
    "C:/Users/username/Pictures/photo.jpg",
    create_backup=False,
    output_path="C:/Users/username/Pictures/photo_no_gps.jpg"
)

6. mask_location_in_photo

选择性地屏蔽特定位置信息。（仅在用户明确要求时运行）

技术特性：

• 首先提取照片的GPS坐标
• 用Haversine公式计算口罩中心点的距离
• 仅在距离为半径以内时删除GPS信息（智能过滤）
• 返回原始位置信息和距离信息（透明）

使用案例：

• “只删除房屋周围500米内照片的位置信息”
• “公司周边只有1公里的照片隐私保护”
• 选择性地删除GPS，仅限特定地区的照片

与LLM的区别： LLM无法进行有条件的文件修改，但该工具执行基于位置的有条件GPS删除。

参数：

• image_path （string）：图像文件路径
• mask_latitude （float）：要遮蔽的中心点的纬度
• mask_longitude （float）：要遮蔽的中心点的经度
• mask_radius_km （float）：要遮蔽的半径（公里）
• create_backup （bool）：如果为True，请使用扩展名.bak备份原始文件，默认值：True
• output_path （string，optional）：保存为新文件的路径（如果为None，则修改原始文件）

返回值：

• JSON格式的操作结果（包括原始位置信息和距离）

示例：

# 집 주변 500m 내 사진의 GPS 정보만 제거
mask_location_in_photo(
    "C:/Users/username/Pictures/photo.jpg",
    mask_latitude=37.5665,
    mask_longitude=126.9780,
    mask_radius_km=0.5,
    create_backup=True
)

📋 支持格式

提取GPS信息

• JPEG（.jpg，.jpeg）-完全支持EXIF元数据
• TIFF（.tiff，.tif）-完全支持EXIF元数据
• PNG（.png）-EXIF阅读支持（有限）

删除/掩蔽GPS信息

• JPEG（.jpg，.jpeg）-完全支持EXIF修改
• TIFF（.tiff，.tif）-完全支持EXIF修改
• PNG（.png）-不支持EXIF数据结构（只读）

技术背景：

• EXIF（Exchange Image File Format）是JPEG/TIFF专用的元数据格式
• PNG无法使用其他元数据结构存储GPS信息
• piexif库准确解析/修改JPEG/TIFF EXIF数据

💡 实际使用示例

示例1:检查单个照片的位置

# 실제 파일에서 GPS 정보 추출
get_photo_location("C:/Users/username/Pictures/vacation/IMG_001.jpg")

# 반환 예시:
# {
#   "image_path": "C:/Users/username/Pictures/vacation/IMG_001.jpg",
#   "location": {
#     "latitude": 33.4996,
#     "longitude": 126.5312,
#     "altitude": 150.5
#   },
#   "address": "제주특별자치도 제주시 해안로, 첨단동",
#   "google_maps_url": "https://www.google.com/maps?q=33.4996,126.5312"
# }

示例2:批量处理整个目录中的照片

# 폴더 내 모든 사진 위치 정보 추출
batch_get_photo_locations("C:/Users/username/Pictures/Korea_Trip_2024")

# 반환: 수백 개 사진의 위치 정보 리스트

示例3:地理击剑-过滤特定地区的照片

# 서울시청에서 5km 반경 내 사진만 찾기
geofence_photos(
    directory_path="C:/Users/username/Pictures",
    center_latitude=37.5665,      # 서울시청 위도
    center_longitude=126.9780,     # 서울시청 경도
    radius_km=5.0,                 # 5km 반경
    filter_mode="inside"           # 반경 내만
)

# 반환: 각 사진의 중심점으로부터의 거리(km) 포함

示例4:隐私保护-完全删除GPS信息

# 사진에서 GPS 정보 제거 (백업 자동 생성)
remove_gps_from_photo(
    image_path="C:/Users/username/Pictures/photo.jpg",
    create_backup=True  # photo.jpg.bak 자동 생성
)

# 반환: 작업 성공 여부 및 백업 경로

示例5:选择性掩蔽-仅家庭周围的照片删除GPS

# 집 주변 500m 내 사진의 GPS 정보만 제거
mask_location_in_photo(
    image_path="C:/Users/username/Pictures/photo.jpg",
    mask_latitude=37.5665,      # 집 위도
    mask_longitude=126.9780,     # 집 경도
    mask_radius_km=0.5,          # 500m 반경
    create_backup=True
)

# 반환: 원본 위치 정보 및 거리 정보 포함

示例6:Base64图像处理

# Base64 인코딩된 이미지 데이터 처리
get_photo_location_from_base64(
    image_base64="data:image/jpeg;base64,/9j/4AAQ...",
    image_format="jpg"
)

# 반환: 일반 get_photo_location과 동일한 형식

🔒 隐私保护功能

此服务器允许用户 只有在明确要求的情况下 删除或屏蔽GPS信息：

• remove_gps_from_photo：删除所有GPS信息
• mask_location_in_photo：选择性删除特定位置周围的GPS信息

安全的基本行为：

• 所有读取功能都是源文件 绝对不会修改
• GPS清除/掩蔽功能 默认情况下创建备份进行
• 用户被 如果没有明确要求 不删除位置信息
• 最大限度地提高源文件的安全性（备份创建后处理）

🎯 作为MCP的技术优势

准确性（Accuracy）

• Haversine公式：考虑地球曲率的精确距离计算（误差\<0.5%）
• EXIF解析：使用piexif库精确提取GPS数据
• 坐标转换：将度/分/秒（DMS）格式精确转换为十进制坐标

可靠性（Reliability）

• 错误处理：处理所有异常情况，包括无文件、格式错误、缺少EXIF等
• 备份系统：文件修改前自动备份，防止数据丢失
• 验证：预先验证文件是否存在，是否支持格式

效率（Efficiency）

• 批处理：高效处理数百到数千个文件
• 管理临时文件：处理Base64时自动清除
• API优化：最小化反向编码API调用并设置超时

可扩展性（Scalability）

• 大规模处理：可以在目录中处理无限数量的文件
• 内存效率：通过文件流处理优化内存使用
• 外部API集成：利用OpenStreetMap Nominam免费API

🔄 MCP与LLM的明显区别

📚 技术堆栈

• FastMCP：MCP服务器框架
• 皮埃西夫：解析和修改EXIF数据
• 枕头（PIL）：图像文件I/O
• HTTPX：反向编码API调用
• OpenStreetMap提名：免费反向编码服务

🎓 算法详细信息

Haversine公式

计算两个点之间距离的公式：

a = sin²(Δlat/2) + cos(lat1) × cos(lat2) × sin²(Δlon/2)
c = 2 × atan2(√a, √(1−a))
distance = R × c  (R = 지구 반경 6,371km)

EXIF GPS数据结构

• 纬度/经度：度/分/秒元组格式→十进制转换
• 古都：分数元组格式→公制单位转换
• 方向参照：反映N/S、E/W方向

💬 实际使用示例（用户发送的句子）

当用户通过MCP使用此工具时，可以发送以下简单的请求：

• “这张照片是在哪里拍的？” → get_photo_location 呼叫
• “帮我找找去年拍的明洞照片” → geofence_photos 呼叫
• “上传到SNS之前，请检查一下有家庭地址的照片，删除地址信息” → mask_location_in_photo 呼叫

______________________________________________________________________

这台MCP服务器不是简单的信息查询，而是执行实际文件系统操作和准确数据处理的实用工具。通过LLM无法进行的物理文件访问、二进制数据解析和数学精确计算，安全高效地管理您的照片位置信息。