Flickr MCP Server

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

14 tools covering photo and album 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_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 |

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 |

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

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

cp .env.example .env

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:

Generate an authorization URL
Open Flickr in your browser to grant access
Ask you to enter the verification code
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"

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
    albums.ts           # Album management tools
  auth/
    oauth-setup.ts      # One-time OAuth setup CLI

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 管理你的相簿、標記照片、整理照片庫。

功能

14 個工具，涵蓋照片與相簿管理：

照片工具

| 工具 | 功能 | 讀/寫 | |------|------|-------| | flickr_search_photos | 依關鍵字、標籤、日期範圍搜尋照片 | 讀 | | flickr_get_photo_info | 取得照片詳細資訊 | 讀 | | flickr_get_photo_sizes | 取得照片各尺寸的圖片 URL | 讀 | | flickr_list_my_photos | 列出自己的照片（含私人照片） | 讀 | | flickr_get_not_in_set | 列出未歸入任何相簿的照片 | 讀 | | flickr_set_photo_tags | 設定照片標籤（覆蓋原有標籤） | 寫 | | flickr_add_photo_tags | 新增標籤（不覆蓋） | 寫 | | flickr_set_photo_meta | 更新照片標題與描述 | 寫 |

相簿工具

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

所有列表/搜尋工具都會回傳縮圖與中等尺寸圖片 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 金鑰

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

cp .env.example .env

在 .env 中填入 FLICKR_API_KEY 和 FLICKR_API_SECRET

3. OAuth 認證

執行互動式設定腳本：

npm run oauth-setup

腳本會引導你：

產生授權 URL
在瀏覽器中開啟 Flickr 進行授權
輸入頁面上顯示的驗證碼
自動將 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 當封面」
「把這些照片移到東京之旅相簿」

API 限制

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

MCP Servers

Flickr MCP Server

Features

Photo Tools

Album Tools

Prerequisites

Setup

1. Clone and install

2. Get your Flickr API key

3. Authenticate with OAuth

4. Build

5. Configure your MCP client

Claude Code

Claude Desktop

Usage Examples

Project Structure

API Rate Limits

License

Flickr MCP Server (正體中文)

功能

照片工具

相簿工具

前置需求

安裝設定

1. 下載並安裝

2. 取得 Flickr API 金鑰

3. OAuth 認證

4. 編譯

5. 設定 MCP 用戶端

Claude Code

Claude Desktop

使用範例

API 限制

Install Package (if required)

Cursor configuration (mcp.json)