PhotoPrism MCP for AI. Find assets by color, not just by folder.
Gemini Works with every AI agent you already use
…and any MCP-compatible client
Connect to your AI in seconds.
PhotoPrism connects your self-hosted media library to any AI client. It lets you search, browse, and retrieve assets from your private photo vault using natural language commands.
You can find images by metadata (like date or color), generate direct URLs for thumbnails, or stream videos—all without leaving the chat window.
What your AI can do
Create oauth token
Generates a new OAuth2 token needed to access the PhotoPrism API.
Get oauth authorize
Retrieves the necessary authorization details for connecting your AI client to PhotoPrism.
Get oauth userinfo
Fetches basic user profile information after successful OAuth authentication.
You ask the agent to find images based on criteria like color, date range, or keywords using search_photos.
The system creates direct links for photo thumbnails in specific resolutions using get_thumbnail_url, which is perfect for embedding assets.
You retrieve a working streaming URL for videos stored in your library via the get_video_url tool.
The agent handles secure token creation and retrieval using tools like create_oauth_token and get_oauth_userinfo.
Ask an AI about this
Waiting for input…
PhotoPrism MCP Server: 7 Tools for Media Management
These seven tools let your agent read metadata, generate image URLs, manage tokens, and stream videos from your private photo library.
Make your AI actually useful.
Add this MCP to Claude, Cursor, or Windsurf and your AI stops guessing. It gets real tools to look things up, take action, and handle the stuff you keep doing by hand.
Start using PhotoPrism on VinkiusCreate Oauth Token
Generates a new OAuth2 token needed to access the PhotoPrism API.
Get Oauth Authorize
Retrieves the necessary authorization details for connecting your AI client to...
Get Oauth Userinfo
Fetches basic user profile information after successful OAuth authentication.
Get Thumbnail Url
Creates a direct URL for a photo's thumbnail, allowing the agent to display it...
Get Video Url
Provides a functional streaming link that allows video playback within your AI...
Revoke Oauth Token
Removes an existing OAuth2 token, ensuring secure data access if credentials are compromised.
Search Photos
Executes a query against your photo library using keywords, colors, or date ranges to find specific images.
Security and governance baked right in.
Pick your AI client below to get set up. Just create a Vinkius account, subscribe, and you're instantly up and running. We handle the entire backend infrastructure, delivering out-of-the-box support for HTTPS Streamable, SSE, and OAuth2—zero messy routing required.
Claude AI
Open Claude Settings
Go to claude.ai, click your profile icon, then navigate to Customize → Connectors.
Add Custom Connector
Click the "+" button and select Add custom connector. Paste your Vinkius endpoint URL:
https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp
Replace [YOUR_TOKEN_HERE] with your token
from cloud.vinkius.com. For OAuth-protected servers, expand
Advanced settings to add credentials.
Start a conversation
Open a new chat. The PhotoPrism integration is available immediately — no restart needed.
Choose How to Get Started
Build a custom MCP for your own tools, or connect a ready-made integration from our catalog.
Build Your Own
Turn any API into an MCP. Import a spec, define Agent Skills, or deploy with MCPFusion.
- Import from OpenAPI, Swagger, or YAML specs
- Create Agent Skills with progressive disclosure
- Deploy to edge with MCPFusion framework
- Built in DLP, auth, and compliance on every call
- Real time usage dashboard and cost metering
- Publish to catalog or keep private
Make Your AI Do More
Start with PhotoPrism, then connect any of our 5,100+ other servers whenever your AI needs more. One click, no limits.
- Use this MCP plus 5,100+ others, all in one place
- Add new capabilities to your AI anytime you want
- Every connection is secured and compliant automatically
- Track usage and costs across all your servers
- Works with Claude, ChatGPT, Cursor, and more
- New servers added to the catalog every week
Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by PhotoPrism. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.
VINKIUS INFRASTRUCTURE
Cloud Hosted
Managed infra
V8 Isolated
Sandboxed per request
Zero-Trust Proxy
No stored credentials
DLP Enforced
Policy on every call
GDPR Compliant
EU data residency
Token Compression
~60% cost reduction
Works with Claude, ChatGPT, Cursor, and more
The Model Context Protocol standardizes how applications expose capabilities to LLMs. Instead of operating in isolation, your AI gains direct access to external platforms, live data, and real-world actions through secure, standardized connections.
This connection provides 7 powerful capabilities that interface natively with Claude, ChatGPT, Cursor, and other compatible AI platforms. No middleware. No custom integration required.
Finding a specific photo shouldn't feel like an archaeological dig.
Today, finding one particular shot means opening the cloud folder, clicking through year-by-year albums, then scrolling past hundreds of shots until you manually spot the right date or subject. If you need a specific angle from 'the client meeting,' you're guessing.
With this MCP server, your agent does the work for you. You just ask it: 'Show me photos of the presentation screen taken in Q4 2023.' The tool runs `search_photos`, filtering by date and subject matter, and spits out exactly what you need.
PhotoPrism MCP Server: Accessing assets directly from chat.
Manual asset retrieval means opening the photo management tool, finding the file ID, going to a separate URL generator page, and then copying multiple links into your script or document. It's a multi-step failure point.
Now, you tell the agent what you need. Whether it's generating a single preview via `get_thumbnail_url` or pulling a whole video stream using `get_video_url`, the entire process is handled in one conversation thread. The data appears when the AI client needs it—nothing more.
What your AI can actually do with this
You connect your private PhotoPrism media library to any AI client through this server. It lets ya search, browse, and pull assets from your own photo vault using plain language commands. Ya're not limited to basic searching; you can find images based on metadata like colors or dates, get direct URLs for thumbnails, stream videos—all without ever leaving the chat window.
Searching Your Vault
The search_photos tool executes a query against your photo library. You tell it what ya're looking for, and it returns specific images matching keywords, date ranges, or colors you specify. If you want pictures taken near the Statue of Liberty from last fall, you just ask, and the agent runs that search immediately.
It finds photos based on criteria like dates or colors using search_photos.
Getting Media Assets
When ya find a photo, ya gotta see it right away. The system uses get_thumbnail_url to create a direct link for a photo's thumbnail. This means the agent can display the preview instantly, perfect for embedding assets into your chat history. If you need different sizes, this tool handles that too.
For videos stored in your library, ya don't download them; you just ask. The get_video_url tool provides a working streaming link. That lets the video play right inside your AI client environment.
Managing Security and Access
To make all this work, the agent manages secure token creation and retrieval. You use create_oauth_token to generate a new OAuth2 token needed for access. Once that's set up, get_oauth_authorize pulls the necessary authorization details so your client can talk to PhotoPrism. After successful authentication, the agent runs get_oauth_userinfo, which fetches basic user profile information.
If you ever need to cut off access—say, if credentials get compromised—you use revoke_oauth_token. This tool removes any existing OAuth2 token, keeping your data safe.
How It All Works Together
The process is dead simple. You subscribe to this server on Vinkius and then plug in your PhotoPrism URL and API Token into the connection settings. Your AI client—whether it's Claude or Cursor—can start searching and viewing your media library right away. When you ask, "Show me photos of dogs taken last summer," the agent runs search_photos.
If those results are good, and you want to see a preview, the agent immediately calls get_thumbnail_url to generate the direct link for display. Then, if one of those results is a video, it uses get_video_url to pull the streaming content. The entire sequence—from authentication (create_oauth_token) to searching, previewing, and playing back—happens automatically within your chat window.
You'll find that you never have to leave the conversation thread to manage or view any of your personal media assets.
019e38d6-e8a4-7274-9b65-a3ea7cd6e64a 
Here's how it actually works
The bottom line is, you connect your existing self-hosted photo vault to your AI workflow without needing to write any code or use a separate UI.
Subscribe to this server on Vinkius, providing your PhotoPrism instance URL.
Input your API Token into the connection settings so the agent can authenticate with your private media library.
Use natural language prompts in your AI client (e.g., 'Find pictures of my dog from last summer') and let the agent execute search_photos.
Who is this actually for?
This setup targets content creators and technical users who need structured access to private assets. It's for the developer who can't rely on manual photo sorting, or the marketing manager who needs specific historical images pulled into a document draft.
Needs to retrieve high-resolution assets (thumbnails and videos) from their archive directly into a writing or coding session.
Manages large, private media collections and needs to query metadata—like finding all photos taken on a specific day—without manually scrolling through thousands of files.
Integrates private data sources (the photo library) into internal AI tooling for automated asset verification or documentation generation.
What Changes When You Connect
Stop wasting time manually browsing archives. You can query your entire private library using search_photos and get results based on metadata like colors or dates—not just file names.
Embedding photos used to mean generating dozens of links. Now, use get_thumbnail_url to instantly generate direct URLs for previews, perfect for embedding into code documentation or reports.
Video access is simple. Instead of needing FTP or a separate player, the get_video_url tool gives you a clean streaming link right in your AI chat interface.
Security management is handled automatically. You don't need to worry about token expiration; the agent manages credentials using tools like create_oauth_token and revoke_oauth_token.
It works with your existing setup. Since it's an MCP server, you connect your private PhotoPrism instance without needing to overhaul your entire development environment.
See it in action
The historical photo pull
A marketing manager needs a picture of 'the office launch' from 2018. Instead of digging through years of folders, they prompt their agent: 'Find photos of the team at the office in 2018.' The agent uses search_photos to narrow down the exact moment and provides multiple options immediately.
The asset documentation task
A developer is writing API docs and needs visual examples. They prompt: 'Get a 400px thumbnail for the photo with hash XYZ.' The agent uses get_thumbnail_url to output the precise URL, which the developer pastes directly into their markdown file.
The video review workflow
A client needs a quick look at raw footage. Instead of downloading gigabytes of video, they ask: 'Show me the streaming link for the camping trip.' The agent uses get_video_url, providing instant access to stream the content within their IDE.
The cleanup and security audit
An archivist suspects a token is exposed. They run the prompt: 'Revoke all my active tokens.' The agent executes revoke_oauth_token, immediately securing the account without manual API calls.
The honest tradeoffs
Trying to search by file path
A user asks: 'Search for C:/Users/Pictures/2023/dog.jpg.' The agent fails because it's looking at metadata, not the local filesystem structure.
You must ask descriptive questions. Instead of paths, use search_photos. For example: 'Find photos of dogs taken in 2023 with blue skies.' This lets the tool read your actual photo data.
Assuming local file access
The user expects the agent to just pull a picture from their hard drive. It can't; it only sees what PhotoPrism reports.
Always remember you're working through the API. To get an image, you first need to query using search_photos, and then request the specific link using get_thumbnail_url or get_video_url.
Ignoring token expiry
The agent fails with a 401 error because the old access token is invalid, leaving the user confused and stopping work.
If you get an authentication error, don't panic. The proper flow involves first running get_oauth_userinfo to check status, then using create_oauth_token to generate a fresh one.
When It Fits, When It Doesn't
Use this server if your media assets are self-hosted (like PhotoPrism) and you need the AI agent to interact with them programmatically. Specifically, it's perfect for workflows that require structured data retrieval—like 'find all images tagged X taken in Y month.'
Don't use this if: 1) your photos are hosted on a simple cloud drive (Google Drive/Dropbox); you need a different file-system integration tool. 2) you just want to browse casually; the power of this server is querying metadata, not browsing folders. If all you need is basic viewing, don't overcomplicate it with OAuth calls when simpler tools will suffice.
Questions you might have
How do I get started with the search_photos tool? +
You start by asking a descriptive question about your library, for example: 'Find all photos of pets taken after June 2023.' The agent translates that into a query using search_photos.
Can I use get_thumbnail_url outside the AI client? +
No. You must run it through your AI client via the MCP framework to generate the necessary context and access the API endpoints securely. It's designed for conversational tool execution.
What is the flow when using create_oauth_token? +
You initiate this process first to establish a new connection token. This makes sure your agent has fresh, valid credentials before it tries to search or stream any media.
Is get_video_url the same as getting the full file? +
No. get_video_url provides a streaming link designed for in-chat playback or embedded use, not a direct download of the raw video file.
How do I manually remove access using the `revoke_oauth_token` tool? +
You must use the revoke_oauth_token command. It immediately invalidates any active session token linked to that user or client ID, ensuring external AI agents can't access your private media library anymore.
What happens if my query in `search_photos` uses metadata PhotoPrism doesn't recognize? +
The system handles unknown tags gracefully; it returns an error code instead of failing. The agent will report this failure clearly, letting you know which filters or keywords need adjustment.
Does `get_oauth_userinfo` reflect my account details regardless of which AI client I use? +
Yes, get_oauth_userinfo pulls data directly from PhotoPrism's core records. The specific AI client you connect through only changes how the request is sent; it doesn't change the source data.
Are there rate limits when I call `get_thumbnail_url` repeatedly? +
Yes, PhotoPrism imposes standard API rate limits to prevent abuse. If you hit the limit, your agent client will receive a specific error code (429), and you'll need to pause and wait before trying again.
Can I search for photos by specific filters like color or camera model? +
Yes! Use the search_photos tool with the q parameter. You can use filters like 'color:blue' or 'camera:iPhone' just as you would in the PhotoPrism web interface.
What thumbnail sizes are available for my photos? +
The get_thumbnail_url tool supports several standard sizes: tile_50, tile_500, fit_720, fit_1280, and fit_1920.
Does this integration support video playback? +
Yes. The get_video_url tool constructs a streaming URL for a specific file hash, allowing you to view your videos directly from the provided link.
We've already built the connector for PhotoPrism. Just plug in your AI agents and start using Vinkius.
No hosting. No infrastructure. No complex setup.
All 7 tools are live and waiting.
You're up and running in seconds.
Gemini Vinkius gives your AI agents access to the full catalog of app connectors, all fully managed, secure, and enterprise-ready. One subscription, every tool you need.
Built, hosted, and secured by Vinkius. You just connect and go.