Skip to main content
Glama
deenesjakoruzh
savethepolarbears

Google Photos MCP Server

by savethepolarbears
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Google Photos MCP 服务器

一个用于 Google 相册集成的模型上下文协议 (MCP) 服务器，使 Claude、Gemini 和其他 AI 助手能够读取、写入和选择您 Google 相册库中的照片。

✅ Picker API 支持 (2025 年 3 月起)

此服务器实现了 Google Photos Picker API，即使在 2025 年 3 月 31 日某些 Library API 作用域弃用后，也能提供完整的相册库访问权限。

功能

状态

API

浏览完整照片库

✅

Picker API

按文本/日期/类别搜索照片

✅

Library API

创建相册并上传照片

✅

Library API

访问应用创建的内容

✅

Library API

Picker API 的工作原理

  1. 调用 create_picker_session — 返回一个用户在浏览器中打开的 URL

  2. 用户从其完整相册库中选择照片

  3. 调用 poll_picker_session — 当 mediaItemsSet 为 true 时，返回选定的照片

Related MCP server: CoreViz MCP

🛡️ 安全声明：已移除 CORS

出于安全考虑，已移除 CORS 中间件（防止针对 localhost 的驱动下载攻击）。

  • ✅ STDIO 模式 (Claude Desktop)：正常工作

  • ✅ 流式 HTTP (Cursor, 服务器到服务器)：正常工作

  • ❌ 浏览器 AJAX：不支持（设计使然）

功能

读取操作

  • 按文本、日期、位置、类别、收藏夹搜索照片

  • 按媒体类型（照片/视频）、日期范围、归档状态进行过滤

  • 获取照片详情，包括 base64 编码的图像

  • 列出相册及其内容

  • 描述可用的过滤功能

写入操作

  • 创建相册并上传照片

  • 使用 create_album_with_media 进行批量上传（最多 50 个文件）

  • 向相册添加文本和位置丰富信息

  • 设置相册封面照片

Picker 操作

  • 创建 Picker 会话以访问完整相册库

  • 轮询会话并检索选定的媒体项

基础设施

  • ⚡ 流式 HTTP 传输 (MCP 2025-06-18 规范)

  • 🔗 带有连接池的 HTTPS Keep-Alive

  • 🔒 操作系统密钥链令牌存储

  • 📊 带有自动跟踪的配额管理

  • 🔄 自动令牌刷新

先决条件

  • Node.js 22.22+

  • 已启用 Photos Library API 的 Google Cloud 项目

  • OAuth 2.0 凭据（Web 应用类型）

设置

1. Google Cloud 设置

  1. 前往 Google Cloud Console

  2. 创建一个新项目（或选择现有项目）

  3. 启用 Photos Library API

  4. 创建 OAuth 2.0 凭据（Web 应用）

  5. 将 http://localhost:3000/auth/callback 添加为授权重定向 URI

  6. 记下您的客户端 ID 和客户端密钥

2. 安装

git clone https://github.com/savethepolarbears/google-photos-mcp.git
cd google-photos-mcp
npm install

3. 配置

cp .env.example .env

编辑 .env：

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
PORT=3000
NODE_ENV=development

4. 构建并运行

npm run build    # Compile TypeScript
npm start        # HTTP mode (for auth & Cursor)
npm run stdio    # STDIO mode (for Claude Desktop)
npm run dev      # Dev mode with live reload

5. 身份验证

  1. 以 HTTP 模式启动：npm start

  2. 在浏览器中访问 http://localhost:3000/auth

  3. 完成 Google OAuth 流程

  4. 令牌会自动保存到操作系统密钥链中

注意：必须先在 HTTP 模式下完成身份验证。之后，切换到 STDIO 模式以供 Claude Desktop 使用。

动态端口

PORT=3001 npm start
# Also update GOOGLE_REDIRECT_URI in .env to match

客户端配置

Claude Desktop (STDIO)

{
  "mcpServers": {
    "google-photos": {
      "command": "node",
      "args": ["/path/to/google-photos-mcp/dist/index.js", "--stdio"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
      }
    }
  }
}

Cursor IDE

STDIO (推荐)：

  • 类型：Command

  • 命令：node /path/to/google-photos-mcp/dist/index.js --stdio

HTTP：

  • 类型：URL

  • URL：http://localhost:3000/mcp

Smithery

# Claude Desktop
npx -y @smithery/cli install google-photos-mcp --client claude

# Cursor IDE
npx -y @smithery/cli install google-photos-mcp --client cursor

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js        # HTTP
npx @modelcontextprotocol/inspector node dist/index.js --stdio # STDIO

可用工具 (19)

搜索与浏览

工具

描述

search_photos

基于文本的照片搜索

search_photos_by_location

按位置名称搜索

search_media_by_filter

按日期、类别、媒体类型、收藏夹、归档进行过滤

get_photo

获取照片详情（可选 base64）

list_albums

列出所有相册

get_album

获取相册详情

list_album_photos

列出相册中的照片

list_media_items

列出所有媒体项

describe_filter_capabilities

所有过滤选项的 JSON 参考

写入与管理

工具

描述

create_album

创建新相册

upload_media

上传本地文件

add_media_to_album

将现有项目添加到相册（最多 50 个）

create_album_with_media

一次调用创建相册 + 上传文件（最多 50 个）

add_album_enrichment

添加文本或位置丰富信息

set_album_cover

设置相册封面照片

Picker API

工具

描述

create_picker_session

启动 Picker 会话以访问完整相册库

poll_picker_session

检查会话状态并检索选定的照片

身份验证

工具

描述

auth_status

检查身份验证状态

start_auth

通过临时本地服务器启动 OAuth 流程

示例查询

"Show me photos from my trip to Paris"
"Find photos of my dog from 2024"
"List my photo albums"
"Upload these vacation photos to a new album called 'Summer 2025'"
"Search for landscape photos from last year, ordered newest first"
"Let me pick some photos from my library" (triggers Picker API)

位置数据

位置数据是近似值，使用 OpenStreetMap/Nominatim 地理编码从照片描述中提取。如果可用，包括纬度/经度、城市、地区、国家。

部署/发布

本项目是一个模型上下文协议 (MCP) 服务器，旨在与 Claude Desktop 或 Cursor 等 AI 客户端一起在本地运行。除了保持您的本地检出或 NPM 安装为最新版本外，无需进行远程部署或发布流程。

故障排除

  • Node 版本：确保您使用的是 Node.js 22.22+，因为不支持旧版本。

  • 身份验证：如果您遇到 GOOGLE_CLIENT_ID is not set 错误或身份验证失败，请验证您的 .env 文件是否存在于根目录中，并包含正确的 Google Cloud 凭据。请记住在切换到 STDIO 模式之前运行 npm start (HTTP 模式) 进行身份验证。

  • 配额问题：适用 Google Photos API 限制。确保您没有达到每天 10,000 次请求的配额限制。服务器通过 quotaManager 跟踪此限制。

  • CORS 错误：服务器有意禁用 CORS 以防止驱动下载攻击。请勿尝试直接从浏览器 AJAX 请求调用服务器。

开发

项目结构

src/
├── index.ts              # HTTP entry point
├── dxt-server.ts         # STDIO/DXT entry point
├── mcp/core.ts           # All tool handlers (19 tools)
├── api/
│   ├── client.ts         # REST client (Library + Picker)
│   ├── photos.ts         # Facade module (re-exports)
│   ├── types.ts          # TypeScript interfaces
│   └── repositories/     # Low-level API calls
├── auth/                 # OAuth, tokens, keychain
├── schemas/              # Zod validation schemas
├── utils/                # Config, logging, quota, retry
└── views/                # HTML templates

测试

npm test              # All tests (Vitest)
npm run test:watch    # Interactive TDD
npm run test:coverage # Coverage report
npm run test:security # Security suite only

质量检查

合并前必须通过以下三项：

npx tsc --noEmit   # Type check
npm run lint        # ESLint
npm test            # Tests

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches