io.github.MK3Core/flickr-mcp
Flickr MCP server — tag photos, write descriptions, set titles, and add photos to groups using AI.
Open source Open in the app JSON README (API)
About
Flickr MCP server — tag photos, write descriptions, set titles, and add photos to groups using AI.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- mk3core
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Last push
- 2026-06-07T01:34:00Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:05
- Updated
- 2026-08-29 03:02:05
- Origin id
io.github.MK3Core/flickr-mcp
README
# flickr-mcp
[](https://www.npmjs.com/package/flickr-mcp)
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=flickr-mcp)
[](https://github.com/sponsors/MK3Core)
An MCP server that gives AI assistants authenticated access to your Flickr photo library. Tag photos, write descriptions, set titles, manage group memberships, and run a full automated processing workflow — all driven by AI, applied to your photos.
Works with any MCP-compatible AI client: Claude, Cursor, Windsurf, and others.
---
## What it does
Once connected, you can ask your AI assistant things like:
- *"Process all my untagged photos"* — scans your whole library, tags and describes everything in one pass
- *"Tag all the photos in my Japan album"*
- *"Write a description for this photo"* (with a Flickr URL or photo ID)
- *"Find my car photos and add them to relevant Flickr groups"*
- *"Look at my recent uploads and add relevant tags to each one"*
The AI looks at your photos visually (via built-in image fetching), generates metadata from the actual image content and EXIF data, and either previews changes before applying or runs fully automated depending on the tool.
---
## Requirements
- Node.js 18 or later
- A **Flickr Pro account** — Flickr requires Pro to register API applications
- An MCP-compatible AI client
---
## Setup
### 1. Register a Flickr API key
> **Note:** Flickr requires a [Pro account](https://www.flickr.com/account/upgrade/pro) to register API applications (~$8/month or ~$72/year). If you're using Flickr seriously enough to want AI-assisted tagging, you likely already have one.
Go to [flickr.com/services/apps/create/noncommercial](https://www.flickr.com/services/apps/create/noncommercial) and fill out the short form — any app name works, select "personal use." It takes about two minutes. Copy the **API key** and **API secret** from the next page.
### 2. Run the setup command
```bash
npx flickr-mcp setup
```
A browser window will open with a setup wizard. Paste your API key and secret, then follow the prompts to authorize access to your Flickr account. Your credentials are saved to `~/.config/flickr-mcp/credentials.json` and never leave your machine.
### 3. Add flickr-mcp to your AI client
The easiest way is to paste the following prompt directly into your AI assistant. It contains everything needed — the config entry, the setup reminder, and a pointer to the full docs:
> Add an MCP server to my config with these details:
>
> - **Name:** `flickr`
> - **Command:** `npx`
> - **Args:** `["flickr-mcp"]`
>
> The full config entry is:
> ```json
> "flickr": {
> "command": "npx",
> "args": ["flickr-mcp"]
> }
> ```
>
> Add this to the `mcpServers` block in my MCP config file, then let me know where you put it and remind me to restart the client.
>
> Full documentation and source: https://github.com/MK3Core/flickr-mcp
Your assistant knows where its own config file lives and will place the entry correctly regardless of which client you're using. After it confirms, restart the client.
<details>
<summary>Prefer to do it manually?</summary>
**Claude Code** — add to `~/.claude/settings.json` (global) or `.claude/settings.json` in a project:
```json
{
"mcpServers": {
"flickr": {
"command": "npx",
"args": ["flickr-mcp"]
}
}
}
```
**Claude Desktop**
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"flickr": {
"command": "npx",
"args": ["flickr-mcp"]
}
}
}
```
**Cursor / Windsurf** — check your client's MCP settings panel, or ask your assistant to find and edit the config file for you.
</details>
---
## Full automated workflow
The quickest way to process your entire library is two tool calls:
1. **`flickr_get_unprocessed_photos`** — scans every photo in your library and returns a list of anything missing tags, a description, or a real title. Raw camera filenames like `DSC_0042` or Lightroom export suffixes like `IMG_1234-Edit` are flagged automatically.
2. **`flickr_process_photo`** — applies title, description, tags, and group assignments to a single photo in one atomic call. The AI fetches the image visually, reads EXIF for camera/lens/location data, generates up to ~20 focused tags following Flickr best practices, writes a concise description, and adds the photo to relevant groups — joining them automatically if needed.
Just ask: *"Process all my untagged photos"* and the AI will page through the unprocessed list and handle each one.
---
## Available tools
These are the tools your AI assistant can call once the server is running. You don't interact with them directly — just describe what you want in plain language.
### Reading your library
| Tool | Description |
|---|---|
| `flickr_list_photos` | List your photostream, paginated |
| `flickr_get_photo` | Full photo details, optionally including the image itself for visual analysis |
| `flickr_get_exif` | Camera metadata: make, model, lens, GPS, shutter speed, ISO |
| `flickr_search_my_photos` | Search your own photos by keyword or tag |
| `flickr_get_albums` | List your albums |
| `flickr_get_album_photos` | List photos inside an album |
### Editing metadata
| Tool | Description |
|---|---|
| `flickr_add_tags` | Add tags to a photo (previews before applying by default) |
| `flickr_remove_tag` | Remove a tag from a photo |
| `flickr_set_metadata` | Set a photo's title and/or description (previews before applying by default) |
### Group management
| Tool | Description |
|---|---|
| `flickr_search_groups` | Search Flickr groups by keyword — returns name, member count, pool size |
| `flickr_join_group` | Join a Flickr group programmatically (accepts group rules automatically) |
| `flickr_add_to_group` | Add a photo to a group pool (previews before applying by default) |
### Automated workflow
| Tool | Description |
|---|---|
| `flickr_get_unprocessed_photos` | Scan your entire library and return photos missing tags, descriptions, or real titles |
| `flickr_process_photo` | Apply title + description + tags + group assignments in one call, with auto-join |
Individual write tools (`flickr_add_tags`, `flickr_set_metadata`, `flickr_add_to_group`) show a dry-run preview before applying. `flickr_process_photo` runs without preview by default — it's designed for batch automation.
---
## Tagging approach
The AI follows Flickr-specific best practices when generating tags:
- **Target ~20 tags** per photo — enough to reach the right audiences without diluting reach
- **Broad + specific subject pairing**: "dog" and "golden retriever", not just one or the other
- **Location chain**: continent, country, region, city, venue where available
- **Gear tags from EXIF**: camera body and focal length (e.g. "sony a7 iv", "85mm")
- **Never**: noise tags ("photo", "image", "picture"), irrelevant popular tags, or tag spam — Flickr's spam policy can hide photos from search
---
## Privacy and scope
This server can only access **your own photos**. It has no ability to read, search, or modify other users' content. The write access it requests is limited to your account.
Your API credentials are stored locally at `~/.config/flickr-mcp/credentials.json` and are never sent anywhere except Flickr's own API.
---
## Rate limiting
The server uses a token bucket that targets 3,000 requests/hour (Flickr's limit is 3,600). Burst of up to 10 requests is allowed. Image fetches count against the budget. Under normal use you will not hit this limit.
---
## Running from source
```bash
git clone https://github.com/MK3Core/flickr-mcp
cd flickr-mcp
npm install
npm run build
node dist/index.js setup
```
Then point your MCP client at `node /path/to/flickr-mcp/dist/index.js` instead of `npx flickr-mcp`.
---
## Support
flickr-mcp is free and open source. If it saves you time, a GitHub sponsorship is always appreciated — it helps justify spending more time on projects like this.
[](https://github.com/sponsors/MK3Core)
---
## Contributing
Issues and pull requests are welcome. The codebase is intentionally small — around 700 lines of TypeScript across six files.
```
src/
index.ts Entry point
setup.ts OAuth setup flow
auth.ts OAuth 1.0a implementation + credential storage
rate-limiter.ts Token bucket (3,000 req/hour)
flickr-client.ts Flickr API wrapper
tools.ts All tool definitions and handlers
```