# PhotoPrism MCP > 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. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** media-management, photo-library, metadata-search, self-hosted, ai-tagging, thumbnails ## Description 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. ## Tools ### 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. ### get_thumbnail_url Creates a direct URL for a photo's thumbnail, allowing the agent to display it immediately. ### get_video_url Provides a functional streaming link that allows video playback within your AI client environment. ### 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. ## Prompt Examples **Prompt:** ``` Search for photos of 'mountains' taken in 2023. ``` **Response:** ``` I found 5 photos of mountains from 2023. Here are the details for the most recent ones... ``` **Prompt:** ``` Get a high-resolution thumbnail for the photo with hash 7af8b9c0. ``` **Response:** ``` I've generated the URL for the 1920px thumbnail of that photo: [URL] ``` **Prompt:** ``` Show me my PhotoPrism account information. ``` **Response:** ``` Retrieving user info... Your account is registered as 'Admin' with the email 'admin@example.com'. ``` ## Capabilities ### Search photos by metadata You ask the agent to find images based on criteria like color, date range, or keywords using `search_photos`. ### Generate image previews and URLs The system creates direct links for photo thumbnails in specific resolutions using `get_thumbnail_url`, which is perfect for embedding assets. ### Stream video content You retrieve a working streaming URL for videos stored in your library via the `get_video_url` tool. ### Manage user authentication The agent handles secure token creation and retrieval using tools like `create_oauth_token` and `get_oauth_userinfo`. ## Use Cases ### 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. ## Benefits - 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. ## How It 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. 1. Subscribe to this server on Vinkius, providing your PhotoPrism instance URL. 2. Input your API Token into the connection settings so the agent can authenticate with your private media library. 3. 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`. ## Frequently Asked Questions **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.