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

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

Photo Tools

Album Tools

Group Tools

Contact Tools

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

Related MCP server: Notion MCP Server

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 個工具，涵蓋照片、相簿、群組與社交管理：

照片工具

相簿工具

群組工具

聯絡人工具

所有列表/搜尋工具都會回傳縮圖與中等尺寸圖片 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 筆，支援分頁