Skip to main content
Glama
deenesjakoruzh
Pexafy

Pexafy MCP Server

Official
by Pexafy
OverviewSchemaSourceRelated ServersScoreDiscussions
Python
Hybrid

pexafy-mcp

CI License: MIT

面向 AI 助手的图库照片搜索工具。 一个 MCP 服务器，让 Claude、ChatGPT 或任何 MCP 客户端都能搜索免版税图片库——可以用自然语言描述场景、用示例图片搜索，或查找“更多类似图片”——并将结果以缩略图网格的形式内联呈现在对话中。

远程 MCP，OAuth 认证，无需粘贴 API 密钥，3 个工具，图片内联渲染。

Pexafy 结果网格内联渲染在 Claude 对话中

使用方法（无需安装）

托管服务器地址为：

https://mcp.pexafy.com/mcp

它使用 Streamable HTTP 协议，并通过 OAuth 2.1 认证：你在浏览器窗口中登录 Pexafy，连接器就会获得自己的凭据。无需生成 API 密钥，也无需将其粘贴到 JSON 文件或日后轮换。

Claude（网页版和桌面版）

  1. 打开 设置 → 连接器（在团队版/企业版中，由管理员在 组织设置 → 连接器 下添加一次）。

  2. 点击 添加自定义连接器。

  3. 粘贴 https://mcp.pexafy.com/mcp 并确认。

  4. 在打开的窗口中登录 Pexafy, 这样就完成了——只要向 Claude 请求一张照片即可。

Claude Code

claude mcp add --transport http pexafy https://mcp.pexafy.com/mcp

其他 MCP 客户端

使用相同的 URL 和 streamable-http 传输方式。不支持 OAuth 的客户端可以使用 Pexafy API 密钥进行认证，只需发送 Authorization: Bearer <key> 或 x-api-key: <key>——可访问 dashboard 获取密钥。

可用性探针：GET /health（公开，无需认证）。

也收录在官方 MCP registry 中，标识为 com.pexafy/pexafy-mcp，同时也在 Smithery 上提供托管网关 URL。

费用

免费版每月支持 5,000 次搜索，且搭配一个连接器，足以满足日常使用，无需绑定银行卡。更高档位请参阅 定价页面。当达到限制时，助手会在聊天中提示你，而不是返回难以理解的错误。

Related MCP server: brave-image-mcp

工具

三个只读工具，没有写入权限，也不会修改账户信息。

search_photos —— 语义文本搜索

用完整句子描述场景；Pexafy 会进行语义理解，因此完整句子比关键词效果好。所有参数均可选，但需要传入 q 或至少一个筛选条件。

参数

类型

说明

q

string

场景的自然语言描述，最多 500 个字符。

color_name

string

可选值：red, orange, yellow, green, blue, purple, pink, brown, black, white, gray, teal, beige, gold, navy。与 color_hex 互斥。

color_hex

string

例如 #1E90FF。与 color_name 互斥。

color_tolerance

integer

0（精确）到 255（宽松）。默认 20。仅在设置 color_hex 时有效。

orientation

string[]

landscape, portrait, square。

source

string[]

Unsplash, Pexels, Pixabay, Kaboompics, Burst, StockSnap, Picjumbo, Skitterphoto, NegativeSpace。

license_type

string[]

free, cc0。

photographer

string

确切的摄影师用户名。

after_date

string

YYYY-MM-DD，指发布日期在当日或之后。

cursor

string

上一次响应中的 pagination.next_cursor。

search_photos_by_image —— 以图搜图，通过示例图片搜索

根据参考图片查找类似的照片，并可搭配文字进行辅助（比如“这张，但要在夜间”）。

参数

类型

说明

image_url

string

参考图片的公开 http(s) URL。

image_file

object

由支持上传的客户端自动填写（例如 ChatGPT）。

image_base64

string

原始 base64 字节，适合编程式客户端。

q

string

可结合图片使用的文本（例如“双手举起来”）。

text_weight

number

q 相对图片的权重。

text_source

string

与上面相同的过滤参数。

cursor

string

分页令牌。

image_url、image_file 或 image_base64 三者必提供其一。图片由服务器端获取，最大不超过 20 MB。

get_similar_photos —— 查找更多相似图片

参数

类型

说明

photo_id

string

必填。 图片的 UUID，来自上一次搜索结果。

cursor

string

分页令牌。

返回内容

每张照片返回其 ID、多种尺寸的 URL、尺寸、主色调、方向、来源、许可证、摄影师，以及一个 attribution 字符串，用于展示图片来源——有足够的信息让助手理解并推理结果，而不仅仅是列出它们。

结果编号为 #1, #2, …，因此可以直接像在对话中一样引用某张照片，无需再复制 ID：

请求更多与 #1 相似的照片，助手对新的一组结果进行推理

在支持 MCP Apps 的客户端中，点击缩略图会打开一个完整元数据的详情面板——无需额外调用，这些数据已经包含在工具结果中：

详情面板：摄影师、来源、分辨率、许可证、主色调、方向和描述

自托管

你不需要这样做——上面托管的服务器才是设计好的接入方式。但该服务器本身是 Pexafy API 的一个简洁客户端，因此你也可以用用自己的 API key 运行自己的实例。

需要 Python 3.12+。

git clone https://github.com/Pexafy/pexafy-mcp.git && cd pexafy-mcp
./run.sh setup        # venv + editable install + seed .env
# edit .env — set PEXAFY_API_KEY
./run.sh dev          # stdio, for Claude Desktop / Claude Code

使用已安装的控制台脚本（pip install .）：

pexafy-mcp                             # stdio (default)
PEXAFY_MCP_TRANSPORT=http pexafy-mcp   # remote Streamable HTTP

Claude Desktop / Claude Code，通过 stdio 传输：

{
  "mcpServers": {
    "pexafy": {
      "command": "pexafy-mcp",
      "env": { "PEXAFY_API_KEY": "pexafy_api_…" }
    }
  }
}

使用 Docker 并通过 HTTP：参见 docker-compose.example.yml：

docker compose -f docker-compose.example.yml up -d
curl localhost:8765/health

镜像本身默认使用 stdio，这是 MCP 客户端驱动容器时所用的传输方式，因此也可以直接运行：

docker run -i --rm pexafy-mcp

在未提供 API key 且无网络连接的情况下，上述都能响应 initialize 和 tools/list 请求，因为工具来自打包的 OpenAPI 快照。只有当运行搜索时才需要 API key。通过 HTTP 提供服务只是设置传输方式，两个 compose 文件都已经做了。

配置

每个设置都是环境变量，且全部可选：在不设置任何变量的情况下，pexafy-mcp 会在 stdio 模式启动，并离线响应 initialize 和 tools/list。其中两个变量值得了解。

变量

默认值

说明

PEXAFY_MCP_TRANSPORT

stdio

本地客户端需要 stdio，远程提供 http 服务用 http

PEXAFY_API_BASE_URL

http://localhost:8000

Pexafy API 地址根——可指向 https://api.pexafy.com，或者你自己的部署

其他内容更多属于部署层配置，而不是个人运行容器的配置，具体见 .env.example：用于 stdio 场景的备用 PEXAFY_API_KEY，用于给内联网格缩略图签名的 PEXAFY_THUMB_BASE_URL 和 PEXAFY_THUMB_HMAC_SECRET，以及配合 MCP_RESOLVE_SECRET 让 HTTP 传输成为 OAuth 资源服务器的 PEXAFY_OAUTH_* 一系列变量。启动服务器时它们都不是必填项。

工作原理

src/pexafy_mcp/
├── server.py     # entry point: builds the server, wires hooks, custom tools, /health
├── tooling.py    # tunes the OpenAPI-derived tools for an LLM (descriptions, value sets)
├── widget.py     # MCP Apps UI resource — the inline result grid (self-contained HTML)
├── previews.py   # signs the thumbnail URLs injected into each result
├── limits.py     # turns plan-limit (429) responses into in-chat upgrade nudges
├── auth.py       # per-user auth: OAuth Resource Server or forwarded API key
└── assets/       # vendored, shipped with the package:
    ├── openapi.json          # OpenAPI snapshot the tools are generated from
    ├── facets.json           # evolving source/license value sets
    └── ext_apps_bundle.js    # @modelcontextprotocol/ext-apps SDK (inlined in the widget)

  • 工具是从 Pexafy OpenAPI 规范通过 FastMCP.from_openapi() 生成的，因此该 API 是唯一事实来源；tooling.py 随后会针对 LLM 进行重塑——收敛到以搜索为核心，去掉可能会误导模型的参数，并内联列出所有有限的取值，因此永远不需要做 facet 查找。

  • build_server() 组装所有内容。导入包不会产生副作用，也不会涉及网络 I/O：它只读取已打包的 assets/openapi.json 和 assets/facets.json。prepare.sh 会重新生成这些文件。

  • search_photos_by_image 是手工编写的：聊天助手无法直接将二进制文件上传到某个 MCP 工具，因此该工具接受图片 URL，并在服务器端获取图片。

  • 内联网格是一个 MCP Apps UI 资源。ext-apps 客户端是内置在包里的，并完全内联，因为宿主的沙箱 iframe 无法在运行时获取外部脚本。

开发

./run.sh test         # offline test suite (pytest)
./run.sh inspect      # MCP Inspector
./prepare.sh          # maintainers: regenerate the vendored assets/

欢迎贡献，详见 CONTRIBUTING.md。

许可

MIT——参见 LICENSE。

该软件包还分发第三方资产（Inter 字体、@modelcontextprotocol/ext-apps 浏览器 bundle，及其打包的库），每个都有自己的许可证——参见 THIRD_PARTY_NOTICES.md。

Available Tools

3 tools
get_similar_photosFind similar photosA
Read-onlyIdempotent
Inspect

Use this tool when the user says 'find something similar', 'show me more like this', or 'I need a visually consistent set'. Requires a photo_id obtained from a previous search result. A person normally refers to a photo by the rank shown on the result grid rather than by its identifier; each search result carries both, in the same object. Each result carries: rank, its position on this page (1, 2, 3, …), which is also the number drawn on the inline grid and the handle a person naturally uses to refer to one photo among several; photo_id, the identifier the similar-photos tool takes, present in the same object as the rank; attribution, the credit line to display with the photo; and urls, the image at several sizes, urls.regular being the one to link to. Inline thumbnails are attached to this tool's result as an MCP App resource. Some clients, claude.ai on the web among them, render that resource only inside an expandable tool panel rather than in the reply itself; where it is not rendered, the photos remain reachable through their URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault
cursorNoToken to fetch the next page. Take `pagination.next_cursor` from a previous response and pass it back here. See the Pagination guide.
photo_idYesThe reference photo's unique Pexafy identifier (a UUID).

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaNo
errorNo
successNo
paginationNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context: the result includes inline thumbnails as an MCP App resource, and warns that some clients (like claude.ai on web) render them only in an expandable panel, with URLs still available. This goes beyond annotations and is valuable for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively lengthy but every paragraph serves a purpose: it explains when to use, prerequisites, how users refer to photos (critical for agent understanding), and display behavior. It is front-loaded with the primary usage trigger and then provides necessary details. Slightly verbose but justified by the need to explain the rank vs. photo_id distinction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return values are covered there. The description compensates for the complexity of the tool by explaining the relationship between rank and photo_id, which is not obvious from the schema. It also addresses pagination and resource rendering behavior. Given the moderate complexity and presence of output schema, this is adequately complete, though more details on what 'similar' entails could be added.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters (photo_id and cursor) described in the schema. The description reinforces the use of photo_id (requires it from a prior search) and explains the cursor's role (pass pagination.next_cursor), but adds minimal additional semantics beyond the schema. Baseline 3 is appropriate given full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds similar photos based on a photo_id, distinct from sibling search tools by focusing on similarity rather than keywords or image upload. It explicitly ties to user phrases like 'find something similar', making its purpose actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly explains when to use the tool ('when the user says...'), specifies the prerequisite (photo_id from a previous search), and details how a person refers to photos (by rank) versus the identifier, which prevents misuse. It also clarifies how to use the cursor for pagination.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_photosSearch photos by descriptionA
Read-onlyIdempotent
Inspect

Use this tool whenever the user needs an image, photo, or visual — for a presentation, blog, website, social-media post, mood board, or any creative project. Pexafy is a SEMANTIC search engine: describe the scene in full natural-language sentences, not keywords. Rich descriptions return far better results than tag-like queries. Good queries: 'a melancholy portrait of an old person sitting under a soft light'; 'two people sharing a bench in comfortable silence'; 'the last sunlight of the day hitting a dusty windowsill'; 'a child discovering snow for the first time'. Prefer this tool over search_photos_by_image when the user describes what they want in words. BUT if they want photos LIKE a specific image that has a URL — a photo from a previous result, or a public URL they gave — use search_photos_by_image instead (pass that URL, plus a q for any change like 'but with hands raised'). Only use THIS text tool for a reference image with NO URL (a file pasted/uploaded in the chat): describe what you see in rich detail — Pexafy is semantic, so a good description finds visually similar photos. Each result carries: rank, its position on this page (1, 2, 3, …), which is also the number drawn on the inline grid and the handle a person naturally uses to refer to one photo among several; photo_id, the identifier the similar-photos tool takes, present in the same object as the rank; attribution, the credit line to display with the photo; and urls, the image at several sizes, urls.regular being the one to link to. Inline thumbnails are attached to this tool's result as an MCP App resource. Some clients, claude.ai on the web among them, render that resource only inside an expandable tool panel rather than in the reply itself; where it is not rendered, the photos remain reachable through their URLs.

ParametersJSON Schema
NameRequiredDescriptionDefault
qNoYour search query as a full natural-language sentence describing the scene you want — Pexafy is semantic, so sentences beat keywords. Up to 500 characters. Optional if you provide at least one filter instead. Example: 'an old man sitting at a café table he has visited every morning for thirty years'.
cursorNoToken used to fetch the next page. Take the `pagination.next_cursor` value from a previous response and pass it back here. See the [Pagination](/pagination) guide.
sourceNoKeep only photos from these providers: Unsplash, Pexels, Pixabay, Kaboompics, Burst, StockSnap, Picjumbo, Skitterphoto, NegativeSpace. Repeat the parameter to pass several.
color_hexNoKeep only photos close to this hex color (e.g. `#1E90FF`). Cannot be combined with `color_name`. Use `color_tolerance` to widen or tighten the match.
after_dateNoOnly return photos published on or after this date, formatted `YYYY-MM-DD`.
color_nameNoKeep only photos whose dominant color matches one of: red, orange, yellow, green, blue, purple, pink, brown, black, white, gray, teal, beige, gold, navy. Cannot be combined with color_hex.
orientationNoKeep only photos with these shapes: landscape, portrait, square. Repeat the parameter to pass several.
license_typeNoKeep only photos with these license types: free, cc0. 'free' means the photo can be used freely and attribution is appreciated. Repeat the parameter to pass several.
photographerNoOnly return photos from this photographer's username. Use `GET /api/v1/facets/photographers/suggest` to find usernames.
color_toleranceNoHow far a photo's color may be from `color_hex` and still match, from `0` (exact match) to `255` (very loose). Defaults to `20`. Only applies when `color_hex` is set.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaNo
errorNo
successNo
paginationNo

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare a safe, read-only, idempotent operation, so the description's job is to add context beyond that. It does: semantic search behavior, result-field semantics (rank, photo_id, attribution, urls), the inline-thumbnail MCP resource, and the rendering caveat on claude.ai. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but it is front-loaded with the primary use case and every section earns its place: query style, examples, sibling distinction, result fields, and rendering behavior. A few example queries could be trimmed without losing meaning, which keeps it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 10 optional parameters, an output schema, and two siblings, the description is complete: it explains semantic querying, when to use each sibling, what each result field means, and how the inline resource may render. The output schema covers return values, so the description correctly focuses on selection and invocation behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3 and the schema already documents every parameter. The description adds real value by teaching the core q semantics, showing strong example queries, and explaining how photo_id connects to the similar-photos sibling, but it does not need to repeat the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific use case ('user needs an image, photo, or visual') and names the resource being searched. It clearly differentiates this text-query tool from search_photos_by_image, which is the main sibling it could be confused with.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('Prefer this tool over search_photos_by_image when the user describes what they want in words') and names the alternative with the exact input it needs. It also handles the edge case of a reference image with no URL, telling the agent to describe it in rich detail instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_photos_by_imageSearch photos by example imageA
Read-onlyIdempotent
Inspect

Find visually similar stock photos from an EXAMPLE IMAGE, optionally TWEAKED with words. This is the right tool for 'find photos LIKE THIS but ' (e.g. 'like this but with their hands raised', 'the same scene but at night'). Give the reference image one of three ways: (1) image_url — a public http(s) link: a photo from a PREVIOUS search result (reuse its image_url/urls.regular), or any public URL the user provides; (2) image_file — auto-filled by the host when the user UPLOADS an image (e.g. ChatGPT) — it is populated by the host, not by the caller; (3) image_base64 — raw base64 image bytes, for a programmatic client that already holds the file. A chat assistant has no access to the exact bytes of an image it was shown, so image_base64 is not available to it. Put any change in q; raise text_alpha to weight the text more. If the reference image has no URL and the host did not auto-provide image_file (e.g. a file pasted into a chat that can't be forwarded), you cannot send it — describe what you see and use search_photos instead. Every result carries an attribution you show.

ParametersJSON Schema
NameRequiredDescriptionDefault
qNoYour search query as a full natural-language sentence describing the scene you want — Pexafy is semantic, so sentences beat keywords. Up to 500 characters. Optional if you provide at least one filter instead. Example: 'an old man sitting at a café table he has visited every morning for thirty years'.
cursorNoToken to fetch the next page. Take `pagination.next_cursor` from a previous response and pass it back here — no need to re-upload the image. See the Pagination guide.
sourceNoKeep only photos from these providers: Unsplash, Pexels, Pixabay, Kaboompics, Burst, StockSnap, Picjumbo, Skitterphoto, NegativeSpace. Repeat the parameter to pass several.
image_urlNoPublic http(s) URL of the reference image. Reuse the `image_url` of a photo from a previous search result, or any public URL the user provides.
after_dateNoOnly return photos published on or after this date, formatted YYYY-MM-DD.
color_nameNoKeep only photos whose dominant color matches one of: red, orange, yellow, green, blue, purple, pink, brown, black, white, gray, teal, beige, gold, navy. Cannot be combined with color_hex.
image_fileNoFilled in by the host when the user uploads an image, not by the caller. Carries the upload's `download_url` and `file_id`.
text_alphaNoBalance between your text and the image when both are provided, from `0` to `10`. `0` ignores the text (pure visual search), `1.7` (the default) is balanced, and higher values give your words more weight. Has no effect without `q`.
orientationNoKeep only photos with these shapes: landscape, portrait, square. Repeat the parameter to pass several.
image_base64NoThe reference image as base64 bytes, optionally as a `data:` URL. For a client that already holds the bytes; prefer `image_url` when a link exists.
license_typeNoKeep only photos with these license types: free, cc0. 'free' means the photo can be used freely and attribution is appreciated. Repeat the parameter to pass several.
photographerNoOnly return photos from this photographer's exact username.

Output Schema

ParametersJSON Schema
NameRequiredDescription
dataNo
metaNo
errorNo
successNo
paginationNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly and idempotent, so the description doesn't need to repeat that. It adds meaningful context beyond annotations: the image_file is host-populated rather than caller-set, image_base64 is unavailable to chat assistants, and every result carries an attribution to display. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place—it covers usage, input methods, edge cases, and attribution. The numbered list of image-providing options is clear and well-structured. It could be slightly trimmed, but the density is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 12 parameters, 100% schema coverage, and an output schema, the description provides all necessary behavioral context: how to provide the reference image, the host-filling behavior of image_file, the text weighting mechanism, and the fallback to search_photos. It also mentions the attribution requirement from results, which is not in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter. The description adds practical nuance beyond the schema, such as how text_alpha weights text against image, and the guidance to put any modification in q. This exceeds the baseline for fully covered schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds visually similar stock photos from an example image, optionally tweaked with words. It explicitly distinguishes from siblings by providing a usage scenario ('find photos LIKE THIS but <change>') and names the alternative (search_photos) when the image can't be sent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance with examples and a concrete fallback: when the image has no URL and no auto-provided file, use search_photos instead. It also explains the three ways to supply the reference image and which is appropriate for different clients.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.4.9
    • Changedsearch_photos_by_image19 fields changed
      • addedInput schema / properties / after_date / description
        Added value: +"Only return photos published on or after this date, formatted YYYY-MM-DD."
      • addedInput schema / properties / color_name / description
        Added value: +"Keep only photos whose dominant color matches one of: red, orange, yellow, green, blue, purple, pink, brown, black, white, gray, teal, beige, gold, navy. Cannot be combined with color_hex."
      • addedInput schema / properties / cursor / description
        Added value: +"Token to fetch the next page. Take `pagination.next_cursor` from a previous response and pass it back here — no need to re-upload the image. See the Pagination guide."
      • addedInput schema / properties / image_base64 / description
        Added value: +"The reference image as base64 bytes, optionally as a `data:` URL. For a client that already holds the bytes; prefer `image_url` when a link exists."
      • addedInput schema / properties / image_file / additionalProperties
        Added value: +false
      • removedInput schema / properties / image_file / anyOf
        Removed value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]
      • removedInput schema / properties / image_file / default
        Removed value: -null
      • addedInput schema / properties / image_file / description
        Added value: +"Filled in by the host when the user uploads an image, not by the caller. Carries the upload's `download_url` and `file_id`."
      • addedInput schema / properties / image_file / properties
        Added value: +{
+  "download_url": {
+    "type": "string"
+  },
+  "file_id": {
+    "type": "string"
+  },
+  "file_name": {
+    "type": "string"
+  },
+  "mime_type": {
+    "type": "string"
+  }
+}
      • addedInput schema / properties / image_file / required
        Added value: +[
+  "download_url",
+  "file_id"
+]
      • addedInput schema / properties / image_file / type
        Added value: +"object"
      • addedInput schema / properties / image_url / description
        Added value: +"Public http(s) URL of the reference image. Reuse the `image_url` of a photo from a previous search result, or any public URL the user provides."
      • addedInput schema / properties / license_type / description
        Added value: +"Keep only photos with these license types: free, cc0. 'free' means the photo can be used freely and attribution is appreciated. Repeat the parameter to pass several."
      • addedInput schema / properties / orientation / description
        Added value: +"Keep only photos with these shapes: landscape, portrait, square. Repeat the parameter to pass several."
      • addedInput schema / properties / photographer / description
        Added value: +"Only return photos from this photographer's exact username."
      • addedInput schema / properties / q / description
        Added value: +"Your search query as a full natural-language sentence describing the scene you want — Pexafy is semantic, so sentences beat keywords. Up to 500 characters. Optional if you provide at least one filter instead. Example: 'an old man sitting at a café table he has visited every morning for thirty years'."
      • addedInput schema / properties / source / description
        Added value: +"Keep only photos from these providers: Unsplash, Pexels, Pixabay, Kaboompics, Burst, StockSnap, Picjumbo, Skitterphoto, NegativeSpace. Repeat the parameter to pass several."
      • addedInput schema / properties / text_alpha / description
        Added value: +"Balance between your text and the image when both are provided, from `0` to `10`. `0` ignores the text (pure visual search), `1.7` (the default) is balanced, and higher values give your words more weight. Has no effect without `q`."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "data": {
+      "items": {
+        "description": "A photo result. Fields returned can be narrowed with the `fields` parameter and may depend on your plan.",
+        "properties": {
+          "alt_description": {
+            "description": "Accessibility-friendly text.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "attribution": {
+            "description": "Ready-to-display credit for the photographer/source.",
+            "properties": {
+              "html": {
+                "description": "HTML attribution snippet.",
+                "type": "string"
+              },
+              "plain": {
+                "description": "Plain-text attribution.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "blur_hash": {
+            "description": "BlurHash placeholder string.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "color_hex": {
+            "description": "Dominant color hex code.",
+            "type": "string"
+          },
+          "color_name": {
+            "description": "Dominant color name.",
+            "type": "string"
+          },
+          "description": {
+            "description": "AI-generated caption.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "height": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "image_url": {
+            "description": "Canonical source image URL.",
+            "format": "uri",
+            "type": "string"
+          },
+          "license_type": {
+            "description": "License type (e.g. `free`).",
+            "type": "string"
+          },
+          "orientation": {
+            "enum": [
+              "landscape",
+              "portrait",
+              "square"
+            ],
+            "type": "string"
+          },
+          "photo_id": {
+            "description": "Unique Pexafy identifier (UUID).",
+            "type": "string"
+          },
+          "photographer_full_name": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "photographer_url": {
+            "format": "uri",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "photographer_username": {
+            "type": "string"
+          },
+          "relevance_score": {
+            "description": "Match score 0–1 (higher is better). Only on search results.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "source": {
+            "description": "Provider (e.g. `Pexels`, `Unsplash`, `Pixabay`).",
+            "type": "string"
+          },
+          "source_description": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source_image_url": {
+            "description": "URL of the photo's page on the provider.",
+            "format": "uri",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "uploaded_on": {
+            "description": "Publication date (YYYY-MM-DD).",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "urls": {
+            "description": "Ready-to-use image links in five sizes.",
+            "properties": {
+              "full": {
+                "format": "uri",
+                "type": "string"
+              },
+              "large": {
+                "format": "uri",
+                "type": "string"
+              },
+              "regular": {
+                "format": "uri",
+                "type": "string"
+              },
+              "small": {
+                "format": "uri",
+                "type": "string"
+              },
+              "thumb": {
+                "format": "uri",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "width": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "error": {
+      "anyOf": [
+        {
+          "properties": {
+            "code": {
+              "description": "Machine-readable error code (e.g. `MISSING_PARAMS`, `PHOTO_NOT_FOUND`).",
+              "type": "string"
+            },
+            "message": {
+              "description": "Human-readable error message.",
+              "type": "string"
+            },
+            "request_id": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "meta": {
+      "properties": {
+        "request_id": {
+          "description": "Unique id for this request (quote it in support tickets).",
+          "type": "string"
+        },
+        "took_ms": {
+          "description": "Server processing time in milliseconds.",
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "pagination": {
+      "anyOf": [
+        {
+          "properties": {
+            "has_more": {
+              "description": "Whether another page exists.",
+              "type": "boolean"
+            },
+            "next_cursor": {
+              "description": "Pass back as `cursor` for the next page; `null` when `has_more` is false.",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "per_page": {
+              "description": "Number of items per page.",
+              "type": "integer"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "success": {
+      "type": "boolean"
+    }
+  },
+  "type": "object",
+  "x-fastmcp-top-level-schema": "PhotoListResponse"
+}
  2. 2 tool updatesv0.4.0
    • Addedget_similar_photos
    • Removedphoto_similar
  3. 3 tool updatesv0.2.0
    • First observedphoto_similar
    • First observedsearch_photos
    • First observedsearch_photos_by_image
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation4/5

Each tool has a clearly documented input type (text query vs. image/file vs. previous photo_id), and the descriptions are explicit about which phrase or condition triggers each tool. However, search_photos_by_image and get_similar_photos both produce visually similar photos, and their boundary (one tweaks by text, the other just fetches similar) could occasionally mislead an agent even with the detailed guidance.

Naming Consistency4/5

All names follow a snake_case verb_noun pattern (search_photos, search_photos_by_image, get_similar_photos), and the shared 'search_photos' prefix on two tools is helpful. The slight deviation is 'get' in get_similar_photos versus 'search' elsewhere for the same core concept, but the pattern is otherwise uniform and predictable.

Tool Count4/5

Three tools is a lean but sensible footprint for a dedicated photo-search server, covering the natural query modalities (text, image, similar-by-id). While each tool does earn its place, the set feels slightly minimal—no dedicated tool for fetching individual photo details, but results already carry URLs and attribution, so it works.

Completeness4/5

The core workflow is complete: text query → results → similar-by-photo_id, and image query → results with tweakable text, covering the main stock-photo search use cases with no dead ends. Minor gaps exist (no downloadable/collections/curated feed support, no orientation/filter parameters), but agents can work around these with richer natural-language calls to search_photos.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Wikimedia-Search-Images

    xiaobenyang-com
    A
    license
    B
    quality
    D
    maintenance
    This MCP server enables AI assistants to search for images on Wikimedia Commons, providing detailed metadata and optional thumbnail combinations to assist AI models in visual comparisons.
    1
    2
    Apache 2.0

  • brave-image-mcp

    ilker-tosun
    F
    license
    A
    quality
    D
    maintenance
    An MCP server that provides image search capabilities via the Brave Image Search API, allowing AI assistants to search images with various filters and perform batch queries.
    2
    1
    -

  • MCP Image Resolver

    ahmaddioxide
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables AI assistants to search for royalty-free images from Pexels and Unsplash using natural language, returning structured results with metadata.
    5
    59
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Pexafy/pexafy-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server