Skip to main content
Glama
flickr-mcp

flickr-mcp

by vulture-s

Flickr MCP

English | 繁體中文

Give Claude direct access to your Flickr — browse your photostream, pull direct image URLs for embedding, upload, and manage albums. A thin Model Context Protocol wrapper around Flickr's official API (OAuth 1.0a signed, read + write).

Status: 🟢 all 10 tools live-verified (6 read + 4 write) against a real ~1500-photo account. The first live upload test surfaced two real bugs in upload_photo — an OAuth multipart-signing failure (401) and a non-ASCII title signing crash — both now fixed (HMAC-SHA1 signed by hand, UTF-8 safe).

Tools

Read

  • whoami — verify auth succeeded (returns the logged-in user id / name)

  • list_albums — list your albums (photosets)

  • list_album_photos — list photos in an album (each with a ready-to-use 1024px URL)

  • search_photos — search (defaults to your own photos only)

  • get_photo_info — full metadata for one photo (title / description / tags / taken date / visibility / page URL)

  • get_photo_sizes — every available size with its direct source URL (the reliable source for embed URLs)

Write

  • upload_photo — upload a local image (private by default, nothing goes public by accident)

  • create_album — create an album (Flickr requires an existing photo as the cover)

  • add_photo_to_album — add a photo to an album

  • set_photo_meta — update a photo's title / description

  • delete_photo — permanently delete a photo (irreversible)

  • delete_album — delete an album (removes only the set; the photos stay in your photostream)

⚠️ delete_photo / delete_album need delete permission. If you authorized with write, re-run python authorize.py for a fresh token (it now requests the delete scope).

Related MCP server: WhatsApp MCP for macOS

Install

git clone https://github.com/vulture-s/flickr-mcp.git
cd flickr-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Get credentials (four strings)

  1. Create an app at https://www.flickr.com/services/apps/create/ (non-commercial is fine) and copy its Key and Secret.

  2. Exchange them for an access token:

    export FLICKR_API_KEY=your_key
    export FLICKR_API_SECRET=your_secret
    python authorize.py

    Open the printed URL → approve → paste the 9-digit code Flickr shows back into the terminal. The script prints the four FLICKR_* variables.

Requests write permission (covers read + upload + album management). The script never writes to disk — you paste the tokens into your config yourself.

Add to Claude Code

Use claude mcp add, or add to your MCP config JSON:

{
  "mcpServers": {
    "flickr": {
      "command": "python",
      "args": ["-m", "flickr_mcp.server"],
      "cwd": "/absolute/path/to/flickr-mcp",
      "env": {
        "FLICKR_API_KEY": "...",
        "FLICKR_API_SECRET": "...",
        "FLICKR_OAUTH_TOKEN": "...",
        "FLICKR_OAUTH_TOKEN_SECRET": "..."
      }
    }
  }
}

Once it's connected, ask Claude to run whoami to confirm auth works.

Typical embedding workflow

  1. list_albums → find the album_id you want

  2. list_album_photos or get_photo_sizes → get each photo's direct URL

  3. Drop the URLs into your own HTML/CSS (images live on Flickr, you control the look)

Notes

  • Upload defaults to private: upload_photo's is_public defaults to False; you must explicitly set it to go public.

  • Credentials never touch git: .env is gitignored; only .env.example is tracked. Prefer passing the four vars via your MCP config's env block.

  • write perms exclude deletion: Flickr's write scope covers upload and album management but not deleting photos — a test upload can only be removed from the Flickr website. Think before you upload.

  • The OAuth token is long-lived; you won't need to re-run authorize.py unless you revoke it in Flickr's account settings.

License

MIT — see LICENSE.

Available Tools

12 tools
add_photo_to_albumC

Add an existing photo to an existing album.

Inputs: album_id (required), photo_id (required). Returns: result

create_albumA

Create a new album (photoset). Flickr requires an existing photo id to be the album cover (primary_photo_id). Returns the new album id.

Inputs: title (required), primary_photo_id (required), description. Returns: result

delete_albumA

Delete an album (photoset). Removes only the album — the photos it held are NOT deleted, they stay in your photostream. Needs 'delete' permission.

Inputs: album_id (required). Returns: result

delete_photoA

Permanently delete a photo from Flickr. IRREVERSIBLE. Needs the token to carry 'delete' permission — re-run authorize.py if you only granted 'write'.

Inputs: photo_id (required). Returns: result

get_photo_infoA

Full metadata for one photo: title, description, tags, dates, visibility, and the Flickr page URL.

Inputs: photo_id (required). Returns: result

get_photo_sizesB

Authoritative list of available sizes for a photo, each with its direct source URL and pixel dimensions. This is the reliable source for embed URLs.

Inputs: photo_id (required). Returns: result

list_album_photosA

List photos in an album. Each photo includes id, title, and a ready-to-use 1024px static URL for embedding.

Inputs: album_id (required), page, per_page. Returns: result

list_albumsA

List the authenticated user's albums (photosets): id, title, photo count, and primary photo id. Use list_album_photos to drill into one.

Inputs: page, per_page. Returns: result

search_photosA

Search photos. By default restricted to the authenticated user's own photos (mine_only). Provide text and/or comma-separated tags.

Inputs: page, tags, text, per_page, +1 more. Returns: result

set_photo_metaA

Update a photo's title and/or description. Flickr's setMeta requires the title, so an existing title is fetched when only description is supplied.

Inputs: photo_id (required), title, description. Returns: result

upload_photoA

Upload a local image file to Flickr. Defaults to PRIVATE so nothing goes public by accident. Returns the new photo id.

Inputs: photo_path (required), tags, title, is_public, +1 more. Returns: result

whoamiA

Verify credentials by calling flickr.test.login. Returns the logged-in user's id and username, or a clear error if auth is not set up.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: auth, albums, album photos, search, photo metadata, sizes, upload, album creation, album membership, metadata update, and deletions. Even similarly named tools like get_photo_info and get_photo_sizes are clearly separated by their descriptions.

    Naming Consistency4/5

    The vast majority of tools follow a clear verb_noun snake_case pattern such as list_albums, upload_photo, and delete_album. The only real deviation is whoami, which is a conventional auth command but not a verb_noun name.

    Tool Count5/5

    Twelve tools is a well-scoped size for a Flickr server covering auth, photo operations, and album operations. Each tool has a clear purpose and none feel redundant or excessive.

    Completeness4/5

    The photo lifecycle is well covered with upload, read, update, and delete, plus size and metadata retrieval. Album coverage has meaningful gaps: no album metadata update and no way to remove a photo from an album, though the core album workflow is still usable.

    Related MCP Connectors

    Related MCP Servers