Promas
Promas (Product Image Scraper)
Promas ist ein automatisierter Produktbild-Scraper und Model Context Protocol (MCP)-Server für KI-Agenten.
Anstatt fragiler, seiten-spezifischer Scraper, die bei jeder Änderung der HTML-Struktur brechen, kombiniert Promas pluggable, suchgesteuerte Erkennung mit einer universellen semantischen Extraktions-Pipeline und erweiterbarem, CDN-bewusstem Upscaling. Es extrahiert zuverlässig Produktfotografie in Master-Auflösung von beliebigen Marken- oder Einzelhandelsseiten (Apple, Nike, Sony, Amazon, Target, B&H, Best Buy, eBay, Shopify-Shops und beliebigen Produkt-URLs).
1. Schnellstart
Option A: Installation von PyPI (Empfohlen)
pip install promas
playwright install chromiumSofort von überall ausführbar:
promas "iPhone 16 Pro"Option B: Mit Docker ausführen (Keine lokale Python-/Playwright-Einrichtung)
# Build the Docker image
docker build -t promas .
# Run the FastMCP Server for your AI Agent
docker run -i --rm promas
# Or run the standalone CLI scraper
docker run --rm promas promas "Sony FX3"Related MCP server: Commerce MCP Server
2. Architektur & Pipeline
graph TD
User([AI Agent / CLI Request]) --> Cache{TTL Disk Cache}
Cache -- "Cache Hit (<0.1s)" --> Return([Return Verified Master Assets])
Cache -- "Cache Miss" --> SearchRouter{Pluggable Discovery}
SearchRouter -->|BRAVE_API_KEY| BraveAPI[Brave Search API]
SearchRouter -->|SERPAPI_API_KEY| SerpAPI[SerpAPI Google]
SearchRouter -->|Default: Free / Zero Keys| BrowserSearch[Stealth Browser Discovery]
BraveAPI --> Scorer[E-Commerce Candidate Scorer]
SerpAPI --> Scorer
BrowserSearch --> Scorer
Scorer --> ParallelScraper[Parallel Multi-Page Scraper]
subgraph Scraping Pipeline
ParallelScraper --> RateLimiter[Domain Rate Limiter]
RateLimiter --> Parser[Universal Extractor: Schema.org, OG, Microdata, DOM]
Parser --> CDNUpscaler[CDN Master Upscalers: Scene7, Nike, Shopify, Amazon...]
end
CDNUpscaler --> Verifier[Async HTTP Verification & pHash Dedup]
Verifier --> CacheStore[(Save to Disk Cache)]
CacheStore --> Return3. Warum Promas? (Vergleich)
Funktion | Rohe Skripte ( | Kostenpflichtige APIs ( | Promas |
Kosten | Kostenlos | 50–500 $+/Monat, wiederkehrend | 100 % kostenlos & Open-Source (MIT) |
Einrichtung & Wartung | Fragile, seiten-spezifische Selektoren; bricht bei Redesigns | Generische HTML-Antworten; erfordert eigene Parser | Suchgesteuert + semantische Schemas + CDN-Upscaler |
Anti-Bot & Rate-Limits | Wird schnell von Cloudflare/Akamai blockiert | Wird in der Cloud gehandhabt | Pro-Domain-Rate-Limiter + Stealth + Tenacity-Retries |
Bildverifizierung | Keine; liefert tote Links und 1x1-Pixel | Grundlegende Statusprüfung | Asynchrone HTTP-Validierung + pHash-perzeptuelle Deduplizierung |
Such-Backends | Hartcodierte Scraper | Eigene API-Scraper | Pluggable (Brave API / SerpAPI / Browser-Fallback) |
Caching | Keines | Zusatzkosten | Integrierter TTL-Disk-Cache (Sub-Sekunden bei wiederholten Abfragen) |
Bildqualität | Erfasst meist nur UI-Thumbnails in niedriger Auflösung | Nur Roh-Bilder der Seite | Master-CDN-Entsperrung (bis zu 2500px+) |
KI-Agenten-nativ | Manueller Wrapper erforderlich | Nur REST-API | Natives FastMCP-Tool-Protokoll + Docker-Support |
4. Such-Backends & Konfiguration
Promas funktioniert zu 100 % sofort einsatzbereit, ohne Konfiguration oder API-Schlüssel.
So funktioniert die Such-Erkennung:
Kostenlos / Standard (keine Einrichtung): Promas nutzt die integrierte Playwright-Stealth-Browser-Engine, um E-Commerce-Kandidaten kostenlos über Bing und DuckDuckGo zu finden.
Brave Search API (für Produktion empfohlen): Wenn
BRAVE_API_KEYgesetzt ist, wechselt Promas zur offiziellen, ToS-konformen API-Erkennung im Sub-Sekunden-Bereich.Kostenlosen Schlüssel erhalten (2.000 kostenlose Abfragen/Monat): Brave Search API
SerpAPI (Alternative): Wenn
SERPAPI_API_KEYgesetzt ist, fragt Promas die Google-Suche über SerpAPI ab.Kostenlosen Schlüssel erhalten (100 kostenlose Abfragen/Monat): SerpAPI
Referenz der Umgebungsvariablen:
Variable | Standard | Beschreibung |
| Keine | Optionaler API-Schlüssel für Brave Search |
| Keine | Optionaler API-Schlüssel für SerpAPI Google Search |
|
| Maximale gleichzeitige Browser-Kontexte |
|
| Maximale gleichzeitige Anfragen pro Ziel-Shop |
|
| Höfliche Verzögerung zwischen Anfragen an dieselbe Domain |
|
| Disk-Caching ein-/ausschalten ( |
|
| Cache-Ablaufzeit in Sekunden |
|
| Asynchrone HTTP-MIME- und Pixelmaß-Prüfung |
|
| pHash-Entfernung nahezu identischer Bildausschnitte |
|
| Empfindlichkeitsschwelle für pHash-Deduplizierung |
5. Verwendung
A. Eigenständige CLI
Nach Produktname suchen:
promas "iPhone 16 Pro"Von einer direkten URL extrahieren:
promas "https://www.apple.com/iphone-16-pro/"Nach bestimmter Domain filtern & Anzahl begrenzen:
promas "Sony FX3" --max-images 5 --site bhphotovideo.comCache umgehen oder Verifizierung deaktivieren:
promas "Nike Air Jordan 1" --no-cache --no-verifyB. FastMCP-Server
Den eigenständigen MCP-Server ausführen:
promas-mcpC. Agenten-Integration (mcp_config.json)
Native Python-Installation:
{
"mcpServers": {
"promas": {
"command": "promas-mcp",
"env": {
"BRAVE_API_KEY": "optional-key-here"
}
}
}
}Docker-Container (Einrichtung ohne Abhängigkeiten):
{
"mcpServers": {
"promas": {
"command": "docker",
"args": ["run", "-i", "--rm", "promas"]
}
}
}6. Multi-Tool-MCP-Suite
Promas stellt KI-Agenten dedizierte, granulare Tools zur Verfügung:
Tool | Zweck | Beschreibung |
| Volle Pipeline | Suchbegriff oder URL -> Automatisierte Erkennung -> Paralleles Scraping -> HTTP-Validierung -> pHash-Deduplizierung -> Master-Fotolinks. |
| Nur Erkennung | Suchbegriff -> Schnelle Rangfolge der Kandidaten-Produktseiten (gibt URLs zurück, ohne Bilder zu scrapen). |
| Nur Extraktion | Bestimmte direkte URL -> Extrahiert Titel und Master-Bild-Assets ausschließlich von dieser Seite. |
7. Richtlinien für Agenten-Systemprompts
Fügen Sie Ihrem KI-Agenten-Systemprompt die folgenden Anweisungen hinzu:
You have access to the `fetch_product_images` tool (Promas), which universally retrieves high-resolution product imagery and official product links from across the web.
GUIDELINES FOR USING PROMAS:
1. When asked for product images, photos, or visual references, call `fetch_product_images(query=<specific product name or direct URL>)`.
2. Do not invent or hallucinate image URLs; strictly return the verified URLs returned by Promas.
3. Render primary high-res images as markdown (e.g. ``) and provide source product links for reference.
4. If a specific store is desired by the user, you can supply `site_filter` (e.g. `site_filter="apple.com"`).8. Ausgabe-Schema
{
"status": "success",
"query": "iPhone 16 Pro",
"title": "Apple iPhone 16 Pro",
"sources_scraped": [
"https://www.target.com/p/apple-iphone-16-pro/-/A-93597960",
"https://www.amazon.com/Apple-iPhone-Version-256GB-Titanium/dp/B0DHJDPYYR",
"https://www.apple.com/shop/buy-iphone/iphone-16"
],
"images": [
"https://target.scene7.com/is/image/Target/GUEST_7c0750b4-ee18-41d4-9309-d08e41619229",
"https://target.scene7.com/is/image/Target/GUEST_4e1ce623-313f-4193-93a4-61dc0fc9da14"
],
"error_message": null
}9. Mitwirken
Beiträge sind herzlich willkommen! Die Unterstützung für Master-Upscaling einer neuen E-Commerce-Plattform oder eines CDN erfordert mit unserem Decorator-Plugin-Registry weniger als 10 Zeilen Code.
👉 Siehe CONTRIBUTING.md für Schritt-für-Schritt-Anleitungen zum Hinzufügen einer neuen CDN-Regel.
10. Tests & Qualitätssicherung
Promas enthält Unit-Tests für reine Parsing-Funktionen, Typprüfungen und Canary-Integrationstests:
# Run unit tests
pytest -v
# Run linting
ruff check .
# Run type checker
mypy promas/ tests/
# Run live golden canary integration tests (hits live sites)
pytest -v --run-integration11. Rechtliche & ethische Nutzung
Nur öffentlicher Zugriff: Promas greift ausschließlich auf öffentlich zugängliche Webseiten zu; es umgeht keine Authentifizierung, Bezahlschranken oder private Logins.
Nutzungsbedingungen: Automatisierter Zugriff kann den Nutzungsbedingungen einzelner Websites unterliegen. Überprüfen Sie vor dem Scraping in großem Umfang immer die ToS- und Robot-Richtlinien der Ziel-Domains oder stellen Sie offizielle Such-API-Schlüssel (
BRAVE_API_KEY/SERPAPI_API_KEY) für ToS-konforme Erkennung bereit.Bildurheberrecht & Namensnennung: Promas löst direkte Bild-URLs auf und gibt sie zurück – es speichert, rehostet oder kopiert keine Mediendateien. Die weitere Anzeige, Speicherung oder kommerzielle Nutzung abgerufener Bilder liegt in der Verantwortung des Nutzers.
12. Lizenz
Dieses Projekt ist unter der MIT-Lizenz lizenziert.
Available Tools
4 toolsfetch_product_imagesA
Universally extracts verified, high-resolution product photography and official sources across the web.
USE THIS TOOL WHEN:
You need product photos, packshots, visual references, or master CDN assets for any physical item.
You want Promas to automatically discover authoritative stores, scrape candidate pages, verify images via HTTP, and deduplicate near-identical photo crops.
EXAMPLE QUERIES:
fetch_product_images(query="Sony FX3 Cinema Camera", max_images=5)
fetch_product_images(query="Nike Air Jordan 1", site_filter="nike.com")
fetch_product_images(query="https://www.target.com/p/apple-iphone-16-pro/-/A-93597960")
RETURNS:
ProductImageResult containing:
status: 'success' or 'error'
title: Cleaned product title
sources_scraped: List of retail & brand URLs visited
images: List of verified master-resolution image URLs (up to 2500px+)
Inputs: query (required), no_cache, max_images, site_filter. Returns: Unified result model returned by Promas.
get_product_images_toolD
Backward-compatible alias for fetch_product_images.
Inputs: query (required), max_images, site_filter. Returns: Unified result model returned by Promas.
scrape_single_urlA
Extracts high-resolution product imagery from a single direct product URL (Extraction only).
USE THIS TOOL WHEN:
You already have an exact product URL (from search_product_urls or user input) and want to extract master photos strictly from that page.
Uses universal Schema.org JSON-LD, OpenGraph, dynamic JS datasets, DOM selectors, and CDN upscalers.
EXAMPLE CALL:
scrape_single_url(url="https://www.apple.com/iphone-16-pro/")
RETURNS:
ProductImageResult containing extracted images and metadata from the specified URL.
Inputs: url (required), no_cache, max_images. Returns: Unified result model returned by Promas.
search_product_urlsA
Discovers and ranks candidate e-commerce product pages for a given query (Discovery only).
USE THIS TOOL WHEN:
You want to find authoritative product detail pages (PDPs) across retailers without downloading or scraping images yet.
You want to preview which stores/URLs exist for a product before selecting one to scrape.
EXAMPLE CALL:
search_product_urls(query="Sony FX3 Cinema Camera", max_urls=3)
search_product_urls(query="MacBook Pro M3", site_filter="apple.com")
RETURNS:
A list of ranked, direct product destination URLs.
Inputs: query (required), max_urls, site_filter. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The three primary tools have clearly distinct purposes: fetch_product_images performs full discovery and scraping, search_product_urls only finds URLs, and scrape_single_url extracts images from a provided URL. The fourth tool is explicitly marked as a backward-compatible alias, so no genuine ambiguity exists.
The main tools follow a verb_noun pattern (fetch_product_images, search_product_urls, scrape_single_url), but the alias get_product_images_tool breaks the pattern by using 'get' and a '_tool' suffix. This is a minor deviation, as the alias is clearly labeled and does not detract from the overall predictability.
With only 4 tools, the server is well-scoped. Each core tool serves a distinct stage in the product image retrieval workflow (discovery, extraction, combined pipeline), and the alias is a harmless addition. The count fits comfortably within the ideal range.
The tool surface completely covers the domain: it offers discovery-only (search_product_urls), extraction-only (scrape_single_url), and a comprehensive pipeline (fetch_product_images). There are no obvious dead ends or missing operations for the stated purpose of retrieving product images.
Maintenance
Related MCP Connectors
Live product search for AI agents across Shopify merchants and major retailers.
The E-commerce Marketplace For Every AI Agent. A Governed Catalog Of 600M+ US Products, Plus Four Agent Ready Capabilities Search, Price Comparison, Product-Vs-Product, And Detailed Q&A.
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
Product discovery for AI agents: ranked products and bundles from the open merchant web.
Related MCP Servers
- AlicenseAqualityDmaintenanceKlarna-style product discovery for AI shopping agents. Makes product catalogs machine-readable so AI agents can search, compare, and purchase products programmatically.6MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to browse product catalogs, search products with filters, and initiate checkouts, generating order summaries and checkout URLs.-

Periskop MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform product discovery from natural language shopping intents, returning ranked products with merchant links without completing checkout.MIT- AlicenseNot gradedqualityBmaintenanceEnables agents to perform structured shopping actions and retrieve targeted product images for visual comparison, matching, and aesthetic recommendations.MIT