Flickr Mcp Server

Flickr MCP Server

An MCP server that lets AI assistants see, describe, tag, and manage photos on your Flickr account. Browse photos and albums, draft titles/descriptions/tags, check stats, discover and submit to groups, read and post comments, and keep local notes — all through the Model Context Protocol.

Prerequisites

• Node.js 18+
• Flickr API key (free at flickr.com/services/apps/create/)
• An MCP-compatible client (Claude Desktop, Claude Code, etc.)

Setup

1. Install and build

git clone https://github.com/soctib/flickr-mcp-server.git
cd flickr-mcp-server
npm install
npm run build

2. Get Flickr API credentials

1. Go to https://www.flickr.com/services/apps/create/
2. Create a new app to get your API Key (consumer key) and Secret (consumer secret)

3. Authorize with Flickr

npm run setup-auth

This will:

• Prompt for your API key and secret (if not already in .env)
• Open a browser window for you to authorize the app on Flickr
• Save OAuth tokens to .env automatically

Flickr OAuth tokens don't expire, so you only need to do this once.

4. Configure your MCP client

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "flickr": {
      "command": "node",
      "args": ["/absolute/path/to/flickr-mcp-server/dist/index.js"],
      "env": {
        "FLICKR_CONSUMER_KEY": "your_key",
        "FLICKR_CONSUMER_SECRET": "your_secret",
        "FLICKR_OAUTH_TOKEN": "your_token",
        "FLICKR_OAUTH_TOKEN_SECRET": "your_token_secret"
      }
    }
  }
}

Alternatively, leave credentials in the .env file and omit the env block.

Available Tools

Photos

Tool	Description
flickr_get_recent_photos	List your recent uploads with metadata. Filter by visibility (public, private, friends, family).
flickr_get_favorites	List your faved photos with metadata and owner names.
flickr_view_photo	Fetch a photo's image and full metadata. Pass up to 10 IDs to view multiple photos at medium size.
flickr_view_thumbs	View multiple photos as 150px square thumbnails. Pass photo IDs, or an album ID to browse visually.
flickr_set_metadata	Update a photo's title and/or description.
flickr_set_tags	Replace all tags on a photo. Multi-word tags must be quoted.

Albums

Tool	Description
flickr_list_albums	List your albums (or another user's public albums) with photo counts and visibility labels.
flickr_get_album	Get photos in a specific album with full metadata.

Groups

Tool	Description
flickr_list_groups	List groups you're a member of, with submission limits.
flickr_search_groups	Search Flickr for groups by topic.
flickr_get_group_recents	Browse recent photos in a group's pool to evaluate activity and fit.
flickr_get_photo_contexts	Get all groups and albums photos belong to. Pass photo IDs, or an album ID to check every photo at once.
flickr_add_to_group	Submit a photo to a group pool. Blocks private photos from being submitted.
flickr_remove_from_group	Remove a photo from a group pool.

Stats & Comments

Tool	Description
flickr_get_activity	Daily activity summary: total views across your account plus which photos got views, faves, and comments.
flickr_get_stats	View your most popular photos by views/comments/favorites, or daily stats for a specific photo (last 28 days).
flickr_get_comments	Read all comments on a photo.
flickr_add_comment	Post a comment on any photo.

Local Notes

Notes are stored in a local SQLite database (notes.db) and never sent to Flickr. Use them for reminders, ideas, group submission plans, or any personal annotations.

Tool	Description
flickr_add_note	Add a note to a photo, album, or group.
flickr_get_notes	Get all notes for a specific photo, album, or group.
flickr_delete_note	Delete a note by ID.
flickr_search_notes	Search all notes by text content.

Troubleshooting

• "OAuth signature invalid" — Re-run npm run setup-auth to refresh tokens.
• "Authentication failed" — Check that all 4 credentials in .env are correct.
• Image not displaying — The server caps images at ~700KB. Very large photos fall back to text-only with a Flickr URL.
• Stats returning empty — photo_daily mode only covers the last 28 days (Flickr limitation). Use popular mode for all-time totals.
• "Not a member" when adding to group — You must join the group on Flickr's website first.
• better-sqlite3 version mismatch — If the server crashes on startup with a NODE_MODULE_VERSION error, run npm rebuild better-sqlite3 using the same Node version that runs the server.

Development

npm run build          # Compile TypeScript
npm start              # Run the server (stdio)
npm run setup-auth     # Re-run OAuth setup

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Disclaimer

This project was vibecoded with Claude. It works, it's tested, but set your expectations accordingly.

License

MIT