An MCP (Model Context Protocol) server that connects AI assistants to the Flickr API. Manage albums, tag photos, and organize your Flickr library through natural language.

Features

27 tools covering photo, album, group, and social management:

Photo Tools

Tool	Description	Read/Write
flickr_search_photos	Search photos by keyword, tags, date range	Read
flickr_get_photo_info	Get detailed photo metadata	Read
flickr_get_photo_sizes	Get image URLs for all available sizes	Read
flickr_get_exif	Get camera & EXIF metadata for a photo	Read
flickr_get_explore	Get photos from Flickr Explore (interestingness)	Read
flickr_list_my_photos	List your own photos (including private)	Read
flickr_get_not_in_set	List photos not in any album	Read
flickr_set_photo_tags	Replace all tags on a photo	Write
flickr_add_photo_tags	Append tags to a photo	Write
flickr_set_photo_meta	Update photo title and description	Write
flickr_set_photo_license	Set photo license (All Rights Reserved, CC, etc.)	Write
flickr_set_photo_perms	Set photo visibility and permissions	Write
flickr_add_favorite	Add a photo to your favorites (like)	Write
flickr_remove_favorite	Remove a photo from your favorites (unlike)	Write
flickr_add_comment	Post a comment on a photo	Write

Album Tools

Tool	Description	Read/Write
flickr_list_albums	List all albums	Read
flickr_get_album_photos	List photos in an album	Read
flickr_create_album	Create a new album	Write
flickr_add_photo_to_album	Add a photo to an album	Write
flickr_remove_photo_from_album	Remove a photo from an album	Write
flickr_edit_album_meta	Update album title and description	Write

Group Tools

Tool	Description	Read/Write
flickr_list_my_groups	List all groups you've joined	Read
flickr_search_groups	Search for groups by keyword	Read
flickr_add_photo_to_group	Submit a photo to a group pool	Write
flickr_leave_group	Leave a group	Delete

Contact Tools

Tool	Description	Read/Write
flickr_follow_user	Follow a user (add as contact)	Write
flickr_unfollow_user	Unfollow a user (remove contact)	Write

All list/search tools return thumbnail and medium image URLs for AI-powered visual analysis.

Prerequisites

• Node.js >= 18
• A Flickr account
• Flickr API key (apply here)

Setup

1. Clone and install

git clone https://github.com/chochinlu/flickr-mcp-server.git
cd flickr-mcp-server
npm install

2. Get your Flickr API key

1. Go to Flickr App Garden
2. Create a new app to get your API Key and API Secret
3. Create a .env file:

cp .env.example .env

4. Fill in FLICKR_API_KEY and FLICKR_API_SECRET in .env

3. Authenticate with OAuth

Run the interactive setup script:

npm run oauth-setup

This will:

1. Generate an authorization URL
2. Open Flickr in your browser to grant access
3. Ask you to enter the verification code
4. Save the OAuth tokens to .env

Flickr OAuth tokens never expire -- you only need to do this once.

4. Build

npm run build

5. Configure your MCP client

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "flickr": {
      "command": "node",
      "args": ["/absolute/path/to/flickr-mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "flickr": {
      "command": "node",
      "args": ["/absolute/path/to/flickr-mcp-server/dist/index.js"]
    }
  }
}

Usage Examples

Once connected, you can ask your AI assistant things like:

• "List all my Flickr albums"
• "Show me photos not in any album"
• "Search my photos tagged with travel"
• "Add tags tokyo, japan, 2024 to photo 12345678"
• "Create a new album called 'Tokyo Trip' with photo 12345678 as the cover"
• "Move these photos into the Tokyo Trip album"
• "List all groups I've joined"
• "Submit this photo to the Street Photography group"
• "Leave all inactive groups with less than 100 photos"
• "Like this photo and follow the photographer"
• "Add this photo to my favorites"

Project Structure

src/
  index.ts              # MCP server entry point (stdio transport)
  config.ts             # Environment variable validation (Zod)
  flickr-client.ts      # Flickr API client with rate limiting
  tools/
    photos.ts           # Photo management tools (incl. favorites)
    albums.ts           # Album management tools
    groups.ts           # Group management tools
    contacts.ts         # Contact/follow tools
  auth/
    oauth-setup.ts      # One-time OAuth setup CLI
scripts/
  batch-set-license.ts  # Batch update all photos to a specified license

API Rate Limits

• Flickr allows 3,600 requests/hour (~1 req/sec)
• The client enforces a 1-second minimum interval between requests
• List endpoints return up to 500 items per page with pagination support

License

MIT

---

Flickr MCP Server (正體中文)

一個 MCP (Model Context Protocol) 伺服器，讓 AI 助手能透過 Flickr API 管理你的相簿、標記照片、整理照片庫。

功能

26 個工具，涵蓋照片、相簿、群組與社交管理：

照片工具

工具	功能	讀/寫
flickr_search_photos	依關鍵字、標籤、日期範圍搜尋照片	讀
flickr_get_photo_info	取得照片詳細資訊	讀
flickr_get_photo_sizes	取得照片各尺寸的圖片 URL	讀
flickr_get_exif	取得照片的相機與 EXIF 資訊	讀
flickr_get_explore	取得 Flickr Explore 精選照片	讀
flickr_list_my_photos	列出自己的照片（含私人照片）	讀
flickr_get_not_in_set	列出未歸入任何相簿的照片	讀
flickr_set_photo_tags	設定照片標籤（覆蓋原有標籤）	寫
flickr_add_photo_tags	新增標籤（不覆蓋）	寫
flickr_set_photo_meta	更新照片標題與描述	寫
flickr_set_photo_license	設定照片授權條款（All Rights Reserved、CC 等）	寫
flickr_set_photo_perms	設定照片可見性與權限（公開/私人）	寫
flickr_add_favorite	將照片加入最愛（按讚）	寫
flickr_remove_favorite	從最愛移除照片（取消按讚）	寫
flickr_add_comment	在照片下發布留言	寫

相簿工具

工具	功能	讀/寫
flickr_list_albums	列出所有相簿	讀
flickr_get_album_photos	列出相簿內照片	讀
flickr_create_album	建立新相簿	寫
flickr_add_photo_to_album	將照片加入相簿	寫
flickr_remove_photo_from_album	從相簿移除照片	寫
flickr_edit_album_meta	修改相簿標題與描述	寫

群組工具

工具	功能	讀/寫
flickr_list_my_groups	列出已加入的所有群組	讀
flickr_search_groups	依關鍵字搜尋群組	讀
flickr_add_photo_to_group	將照片投稿到群組	寫
flickr_leave_group	退出群組	刪除

聯絡人工具

工具	功能	讀/寫
flickr_follow_user	追蹤使用者（加入聯絡人）	寫
flickr_unfollow_user	取消追蹤（移除聯絡人）	寫

所有列表/搜尋工具都會回傳縮圖與中等尺寸圖片 URL，方便 AI 進行視覺分析。

前置需求

• Node.js >= 18
• Flickr 帳號
• Flickr API 金鑰（在此申請）

安裝設定

1. 下載並安裝

git clone https://github.com/chochinlu/flickr-mcp-server.git
cd flickr-mcp-server
npm install

2. 取得 Flickr API 金鑰

1. 前往 Flickr App Garden 建立應用程式
2. 取得 API Key 與 API Secret
3. 建立 .env 檔案：

cp .env.example .env

4. 在 .env 中填入 FLICKR_API_KEY 和 FLICKR_API_SECRET

3. OAuth 認證

執行互動式設定腳本：

npm run oauth-setup

腳本會引導你：

1. 產生授權 URL
2. 在瀏覽器中開啟 Flickr 進行授權
3. 輸入頁面上顯示的驗證碼
4. 自動將 OAuth token 存入 .env

Flickr 的 OAuth token 永不過期，只需設定一次。

4. 編譯

npm run build

5. 設定 MCP 用戶端

Claude Code

在專案的 .mcp.json 中加入：

{
  "mcpServers": {
    "flickr": {
      "command": "node",
      "args": ["/absolute/path/to/flickr-mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "flickr": {
      "command": "node",
      "args": ["/absolute/path/to/flickr-mcp-server/dist/index.js"]
    }
  }
}

使用範例

連線後，你可以用自然語言請 AI 助手幫你：

• 「列出我所有的 Flickr 相簿」
• 「找出沒有歸入任何相簿的照片」
• 「搜尋標記了 travel 的照片」
• 「幫照片 12345678 加上 tokyo、japan、2024 標籤」
• 「建立一個叫『東京之旅』的新相簿，用照片 12345678 當封面」
• 「把這些照片移到東京之旅相簿」
• 「列出我加入的所有群組」
• 「把這張照片投稿到街拍群組」
• 「退出所有照片數不到 100 的不活躍群組」
• 「幫我對這張照片按讚，然後追蹤這個攝影師」
• 「把這張照片加入我的最愛」

API 限制

• Flickr 允許每小時 3,600 次請求（約每秒 1 次）
• Client 內建 1 秒最小間隔的速率限制
• 列表類 API 每頁最多 500 筆，支援分頁