Skip to main content
Glama
Kreminskaya

pinterest-vision-mcp

by Kreminskaya
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

pinterest-vision-mcp

🔍 pinterest-vision-mcp

Python License: MIT MCP ChromaDB

MCP server that gives AI agents visual intelligence — search Pinterest, analyze images with LLM vision, build a semantic reference library, and retrieve by style or mood.

Why

AI agents are good at text. They're not good at having taste.

When building AI production workflows, I kept running into the same problem: an agent could write a creative brief but couldn't tell a quiet luxury editorial from a fast fashion product shot. To make agents genuinely useful for visual work, they need a visual memory — a structured, searchable library of aesthetic references they can learn from and query.

Pinterest is the largest public mood board on the internet. This server connects it to your agents.

Related MCP server: mcp-see

✨ Features

  • 🔎 Pinterest search — query any visual style, aesthetic concept, or reference

  • 📥 Image download — bulk save to local storage, organized by session and query

  • 🧠 LLM vision analysis — structured tags per image: lighting, mood, palette, segment, shot type, brand feel

  • 🗃️ Vector storage — ChromaDB with semantic embeddings

  • 🔁 One-call pipeline — pinterest_pipeline runs the full workflow in a single tool call

  • 🔍 Semantic retrieval — visual_search finds references by vibe, not just keywords

How it works

search → download → LLM vision analysis → ChromaDB → semantic retrieval

  1. Search Pinterest for visual references

  2. Download images locally, organized by date and query

  3. Analyze each image with a vision LLM → structured aesthetic tags

  4. Store in ChromaDB vector database

  5. Retrieve semantically — "dark masculine editorial close-up" finds the right images even if those words aren't in the original captions

Or run the full pipeline in one call with pinterest_pipeline.

Use cases

Creative AI workflows — give agents a visual vocabulary. Instead of relying on text descriptions alone, agents query the library for structured references and use their extracted parameters to guide image generation.

Visual direction — an agent briefing an image model pulls references from the library, extracts their lighting type, composition, and palette, and uses those as structured input.

Style consistency — build a visual library from existing brand photography, then use visual_search to verify that new images match the established aesthetic.

Moodboard automation — agents autonomously search, analyze, and organize visual inspiration around any brief.

Requirements

  • Python 3.10+

  • API key for any OpenAI-compatible vision API (OpenRouter, OpenAI, Groq, etc.)

Cost note: image analysis calls a vision LLM. With anthropic/claude-sonnet-4-6 via OpenRouter, 8 images cost roughly $0.01–$0.05.

Quick Start

git clone https://github.com/Kreminskaya/pinterest-vision-mcp.git
cd pinterest-vision-mcp
pip install -e .
cp .env.example .env
# set VISION_API_KEY in .env

MCP configuration

Works with any MCP-compatible client — Claude Desktop, Cursor, Hermes, or your own agent. Replace /absolute/path/to/pinterest-vision-mcp with the real path.

{
  "mcpServers": {
    "pinterest-vision": {
      "command": "python",
      "args": ["-m", "pinterest_vision_mcp.server"],
      "cwd": "/absolute/path/to/pinterest-vision-mcp",
      "env": {
        "VISION_API_KEY": "your_key_here"
      }
    }
  }
}

The same JSON block works across all clients that support MCP stdio transport.

Environment variables

Variable

Default

Description

VISION_API_KEY

—

Required. API key for your LLM provider

VISION_API_BASE_URL

https://openrouter.ai/api/v1

Base URL (any OpenAI-compatible API)

PINTEREST_VISION_MODEL

anthropic/claude-sonnet-4-6

Any vision-capable model

PINTEREST_DATA_DIR

./data

Directory for downloaded images

CHROMA_PERSIST_DIR

./data/chroma

ChromaDB vector storage path

Supported providers:

# OpenRouter (Claude, GPT-4o, Llama, and 200+ more)
VISION_API_BASE_URL=https://openrouter.ai/api/v1
PINTEREST_VISION_MODEL=anthropic/claude-sonnet-4-6

# OpenAI
VISION_API_BASE_URL=https://api.openai.com/v1
PINTEREST_VISION_MODEL=gpt-4o-mini

# Groq
VISION_API_BASE_URL=https://api.groq.com/openai/v1
PINTEREST_VISION_MODEL=llama-3.2-11b-vision-preview

Tools

Tool

Description

pinterest_search

Search Pinterest by query — returns pins with image URLs

pinterest_download

Download images from search results to local disk

pinterest_analyze

Analyze images with LLM vision — returns structured aesthetic tags

pinterest_ingest

Store analyses in ChromaDB for semantic retrieval

pinterest_pipeline

Full pipeline in one call: search → download → analyze → store

visual_search

Semantic search across stored visual references

Visual analysis schema

Each analyzed image returns:

Field

Example values

lighting_type

natural, studio, golden hour, overcast

composition_type

centered, rule-of-thirds, flat lay, symmetrical

camera_distance

close-up, medium, full body, detail shot

mood

editorial, minimal, dark, romantic, energetic

palette

free-text color description

segment

luxury / premium / contemporary / streetwear

shot_type

campaign editorial / e-commerce product / lookbook

garment_focus

clothing items featured

styling_signals

styling details and accessories

brand_feel

brand aesthetic impression

overall_quality

reference-worthy / average / not useful

raw_description

2–3 sentence summary

Usage

# Full pipeline — search, download, analyze, store in one call
result = pinterest_pipeline(
    query="quiet luxury beige coat editorial",
    limit=15,
    max_download=8,
)
# "Complete: 15 found, 8 downloaded, 8 analyzed, 8 stored"

# Semantic search across the visual library
refs = visual_search(
    query="dark masculine editorial close-up",
    segment="luxury",
    shot_type="campaign editorial",
    n_results=10,
)

# Step-by-step (for more control)
search = pinterest_search(query="minimal white studio editorial", limit=20)
download = pinterest_download(search_result=search, max_images=10)
analyses = pinterest_analyze(image_paths=[a["local_path"] for a in download["downloaded"]])
pinterest_ingest(analyses=analyses, query="minimal white studio")

First run note

On the first call to pinterest_ingest or pinterest_pipeline with ingest=True, ChromaDB downloads a sentence transformer embedding model (~90 MB). This happens once and is cached locally.

Disclaimer

Uses pinterest-dl for Pinterest access. Use responsibly per Pinterest's Terms of Service.

License

MIT

Available Tools

6 tools
pinterest_analyzeA

Analyze images with LLM vision. Returns structured visual tags per image. Tags: lighting_type, composition_type, camera_distance, mood, palette, segment, shot_type, garment_focus, styling_signals, brand_feel, overall_quality. Args: image_paths: local file paths to images model: optional OpenRouter model override (default from PINTEREST_VISION_MODEL env)

ParametersJSON Schema
NameRequiredDescriptionDefault
image_pathsYes
modelNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

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

With no annotations, the description should disclose behavioral traits. It explains it uses LLM vision and returns tags, but omits important details like error behavior upon invalid paths, rate limits, or whether it is read-only. This is insufficient for full transparency.

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

Conciseness5/5

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

The description is concise, front-loads the purpose, lists tags and args in a structured manner. Every sentence adds value with no redundancy.

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

Completeness3/5

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

While it covers core functionality and parameters, it lacks usage guidelines and behavioral transparency. Given an output schema exists, return value details are not needed, but the description could be more complete regarding error scenarios and prerequisites.

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 0%, so the description compensates by explaining image_paths as 'local file paths' and model as an optional override with default from env. This adds meaningful context beyond the bare 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 clearly states it analyzes images with LLM vision and returns structured visual tags, listing all tags. This distinguishes it from sibling tools like pinterest_download or visual_search, as it focuses on analytical output.

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

Usage Guidelines3/5

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

The description implies usage for image analysis but does not explicitly contrast with alternatives like visual_search or state when not to use. The context is clear but lacks exclusions or explicit guidance.

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

pinterest_downloadA

Download images from a pinterest_search result to local filesystem. Saves to {PINTEREST_DATA_DIR}/pinterest/{date}/{query_slug}/ Args: search_result: output dict from pinterest_search max_images: max images to download (default 10)

ParametersJSON Schema
NameRequiredDescriptionDefault
search_resultYes
max_imagesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior3/5

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

With no annotations, the description carries the burden. It details the save directory and default max_images, but omits potential behaviors like overwrite policy, rate limits, or handling of missing images.

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

Conciseness5/5

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

The description is concise, with three clear sentences listing purpose, save path, and parameter descriptions. No redundant information.

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 output schema exists (not shown), the description need not explain return values. It adequately covers both parameters, save location, and default behavior for a focused download tool.

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

Parameters5/5

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

Schema coverage is 0%, so the description compensates fully. It explains search_result as the output from pinterest_search and max_images with its default and purpose, adding meaning beyond the empty 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 clearly states the tool downloads images from pinterest_search results to a local filesystem, specifying the save path. This distinguishes it from sibling tools like pinterest_search, pinterest_analyze, etc.

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

Usage Guidelines4/5

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

The description implies usage after obtaining a pinterest_search result, as it explicitly takes search_result as input. No explicit when-not-to-use or alternatives, but the sibling tools cover other operations, making the use case clear.

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

pinterest_ingestA

Store visual analyses in ChromaDB vector base for future semantic retrieval. Note: on first run, ChromaDB will download an embedding model (~90 MB). Args: analyses: output list from pinterest_analyze query: optional label for what was searched

ParametersJSON Schema
NameRequiredDescriptionDefault
analysesYes
queryNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries full burden. It discloses a key side effect: on first run, ChromaDB downloads a ~90 MB embedding model. However, it omits other behaviors like whether storage is additive or destructive, idempotency, or network requirements. The disclosed behavior is valuable but not exhaustive.

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

Conciseness5/5

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

The description is extremely concise: three sentences total, with the core purpose in the first sentence. The note about the model download is placed after the purpose but is critical. The bullet-style args are clear and avoid fluff. Every sentence is justified.

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?

Given the tool's simplicity (2 params, no nested objects) and the existence of an output schema (described as 'has output schema: true'), the description covers the main functional aspects: what it does, what it takes, and a key behavioral note. It lacks details on storage semantics (e.g., deduplication, overwrite behavior) but is largely sufficient for an agent to use it correctly.

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 description coverage is 0%, so the description must compensate. It explains 'analyses' as output from pinterest_analyze and 'query' as optional label. This adds meaning beyond the schema (which shows only types and required status) but lacks detail on the expected structure of analyses (e.g., exact fields) or query format.

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 stores visual analyses in ChromaDB for future semantic retrieval, distinguishing it from sibling tools like pinterest_analyze (analysis) and visual_search (search). The verb 'store' is specific, and the resource 'ChromaDB vector base' is well-defined, with input tied to pinterest_analyze output.

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

Usage Guidelines3/5

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

The description implies usage after pinterest_analyze (by specifying 'output list from pinterest_analyze') but does not explicitly state when to use or not use this tool versus alternatives. There is no guidance on prerequisites or when to skip this step, leaving the agent to infer context from sibling tool names.

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

pinterest_pipelineA

Full visual intelligence pipeline: search → download → analyze → store. Note: on first run with ingest=True, ChromaDB will download an embedding model (~90 MB). Args: query: search query, e.g. 'minimal editorial white shirt studio' limit: max pins to search (default 15) max_download: max images to download and analyze (default 8) analyze: run LLM vision analysis (default True) ingest: store results in vector base (default True)

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
limitNo
max_downloadNo
analyzeNo
ingestNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

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

With no annotations, the description must disclosure behavioral traits. It mentions that ChromaDB will download an embedding model on first run with ingest=True. However, it does not disclose other potential side effects like API rate limits, cost, or data persistence details.

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

Conciseness5/5

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

The description is concise and well-structured: a single line for the purpose, a note about model download, then a bullet-like list of arguments. Every sentence adds value with no redundancy.

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 5 parameters (1 required) and an output schema (not shown). The description covers the pipeline steps and parameters adequately. It could mention error conditions or prerequisites (e.g., API key), but overall it is fairly complete.

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 0%, so the description provides necessary parameter explanations. It describes each parameter's purpose (e.g., 'search query', 'max pins to search') and mentions defaults, adding significant value beyond 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 clearly states it is a 'full visual intelligence pipeline' consisting of search, download, analyze, and store steps. This distinguishes it from sibling tools like pinterest_search, pinterest_download, pinterest_analyze, and pinterest_ingest, which are individual steps.

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

Usage Guidelines4/5

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

The description explains the tool's purpose and provides parameter details. It notes a side effect (model download on first run with ingest=True). However, it does not explicitly state when to use this tool versus alternatives or provide exclusions.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a distinct purpose: search retrieves pins, download saves images, analyze extracts visual tags, ingest stores results, pipeline runs the full workflow, and visual_search queries stored analyses. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern: 'pinterest_search', 'pinterest_download', 'pinterest_analyze', 'pinterest_ingest', 'pinterest_pipeline', and 'visual_search'. No mixing of conventions.

Tool Count5/5

With 6 tools, the server is well-scoped for its purpose of Pinterest-based visual analysis and retrieval. Each tool covers a necessary step in the pipeline without redundancy.

Completeness4/5

The tool set covers the full workflow from search to semantic querying. However, there is no tool for deleting or updating stored analyses, which could be considered a minor gap.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-see

    sanity-labs
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI agents the ability to observe and understand images via multi-provider vision, object detection, hierarchical analysis, and color extraction.
    17
    2
    MIT

  • cosmos-mcp

    mrmos
    A
    license
    Not graded
    quality
    C
    maintenance
    Unofficial MCP server for cosmos.so that enables AI agents to search visual content, find similar images, and create/manage collections to build moodboards.
    35
    3
    MIT

  • mcp-six-eyes

    RimunAce
    A
    license
    A
    quality
    A
    maintenance
    MCP server that gives text-only AI agents the ability to understand images via vision tools, including multi-image analysis, OCR, comparison, and structured extraction. It uses providers like OpenAI, Anthropic, Gemini, and OpenRouter to return plain text descriptions.
    4
    10
    177
    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/Kreminskaya/pinterest-vision-mcp'

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