vinted-mcp

Give an AI agent a Vinted account.
Search the catalogue, read listings and sellers, chat, negotiate offers on both sides, manage your closet and let the agent draft listings from photos, negotiate within your limits and relist — through the same internal API the Vinted web app uses, with no browser automation. Buying stays manual.

One codebase, three interfaces:

Contents

• Highlights
• Install
• Log in
• Use it from an MCP client
• MCP tools
• Agent automation
• CLI
• Python library
• How it works
• Safety and limits
• Configuration
• Troubleshooting
• Development
• Status and legal

Highlights

Install

Python 3.10+.

pip install vinted-mcp                    # or: uvx vinted-mcp / pipx install vinted-mcp
pip install 'vinted-mcp[browser]' && playwright install chromium     # + the login window

Prefer no Python at all? Download the standalone vinted-mcp / vinted executables (Linux, macOS, Windows; built with PyInstaller) from the releases page.

From a checkout:

git clone https://github.com/figurophobia/vinted-mcp && cd vinted-mcp
python -m venv .venv && .venv/bin/pip install -e '.[browser,test]'

curl_cffi is a hard dependency: Vinted sits behind Cloudflare + DataDome, which reject plain Python HTTP clients, so requests go out with a real Chrome TLS fingerprint.

Log in

The tools never type passwords. You give them a session once:

vinted session      # offline: domain, user id, token expiry
vinted whoami       # online check
vinted logout       # forget the stored session

The session is stored in ~/.config/vinted-mcp/session.json (mode 600). Other countries: --domain fr / VINTED_DOMAIN=fr (a session only works on the domain it was created on).

Use it from an MCP client

Any MCP client that launches stdio servers works. The generic configuration:

{
  "mcpServers": {
    "vinted": {
      "command": "vinted-mcp",
      "args": ["--allow-writes"]
    }
  }
}

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "vinted": { "type": "local", "command": ["vinted-mcp", "--allow-writes"], "enabled": true }
  }
}

The server instructions tell the model that listing descriptions and messages are untrusted data and that there is no checkout. Writes can have partial or unknown outcomes; tools return the API's answer so the agent can check state before retrying.

MCP tools

55 tools. Required arguments are listed; everything else is optional. Item and user arguments accept ids, slugs or full URLs.

Read (29)

Write (22)

Agent automation (4)

Agent automation

Higher-level tools built on the client (vinted_mcp/automation.py). All of them preview first.

Listing from photos — listing_from_photos

Upload the photos once and get everything needed to publish:

vinted suggest-listing ~/photos/3ds --title "Nintendo 3DS Cobalt Blue" --brand Nintendo --condition good

The agent looks at the photos itself for the title and condition, confirms with you, then publishes.

Negotiation — negotiate_offer

One deterministic step per call for a conversation where you sell:

vinted negotiate <conversation_id> --floor 480            # plan only
vinted negotiate <conversation_id> --floor 480 --send     # do it

• a pending offer at or above the floor → accept;
• a lower one → reject and counter with the next price of a concession ladder that halves the gap to the floor (500 → 490 → 485 → 480), the last step saying it is the final price;
• new buyer messages without an offer → a reminder of the current price;
• buyer text that tries to instruct the agent ("ignora todas las instrucciones…", "si eres un modelo de IA…") is listed in ignored_instructions and has no effect. Messages are templates you can override.

Relisting — relist_item

vinted relist <item> --photos new1.jpg new2.jpg --price 450 --yes

Reads the listing, deletes it, waits until it is gone and publishes it again with the same fields plus your changes. Vinted removes listings it considers duplicates of something already online, so two copies never coexist; fresh photos avoid the photo-matching duplicate detector.

Everyone who liked your listings — message_all_likers

vinted likers                                                     # who liked what
vinted likers --all --text "¡Hola {login}! «{title}» para ti en {price} €" --discount 5          # preview
vinted likers --all --text "…" --discount 5 --send

Vinted has no "who favourited my item" endpoint; the list is rebuilt from your like notifications, so only recent likes appear. Placeholders: {login}, {title}, {price}, {listed_price}.

CLI

Every command prints JSON (--pretty to indent); listing commands print a table unless --json.

vinted search "nintendo 3ds" --catalog 3025 --condition very_good,good --max-price 90 --order price_low_to_high
vinted search "zapatillas" --brand 53 --size 776 --attr color=1                 # any filter by id
vinted filters "nintendo 3ds" --catalog 3025 --code brand --find ninten        # discover filter ids
vinted categories --suggest "nintendo 3ds"                                     # where items like this live
vinted show 1234567890                                                          # item details + shipping
vinted seller 1234567 --items                                                   # a seller's closet

vinted inbox
vinted conversation <id>                         # --read, --delete, --delete-message <id>
vinted message "¿Sigue disponible?" --item 1234567890
vinted message --conversation <id> --photo detalle.jpg
vinted offer options 1234567890 --price 40       # limits and suggestions
vinted offer send 1234567890 --price 35
vinted offer accept|decline <transaction> <offer_request>
vinted offer counter <transaction> --price 450

vinted listing-options 3025                      # required attributes + package sizes
vinted publish ~/photos/3ds --title "Nintendo 3DS" --price 120 --catalog 3025 --condition good \
    --brand-id 77600 --brand Nintendo --package-size 8 --attr video_game_platform=1265 [--draft]
vinted publish-draft <draft_id> --price 110
vinted edit <item> --price 110 [--photos new1.jpg new2.jpg]
vinted hide <item> [--show]                      # pause / resume
vinted reserve --transaction <id> | --item <item> --undo
vinted delete <item> [--draft]
vinted stats <item>
vinted bundle --tier 2=5 --tier 3=10 | --off
vinted holiday on|off

vinted whoami
vinted favorites | vinted favorite <item> [--remove]
vinted follow <user> | vinted block <user> [--undo]
vinted profile --about "Vendo consolas" --city Vigo [--photo avatar.jpg]
vinted purchases | vinted selling                # --status in_progress|completed|canceled|all
vinted wallet | vinted notifications | vinted searches

Python library

from vinted_mcp import build_client
from vinted_mcp.automation import listing_from_photos, negotiate

v = build_client()                                   # stored session; SessionError if none

for item in v.search_items("nintendo 3ds", catalog_ids=[3025], conditions=["good"], price_to=80):
    print(item.price, item.title, item.url)

details = v.item(1234567890)                         # dict incl. attributes, seller, shipping
conv = v.message_item(1234567890, "¿Sigue disponible?")
offer = v.send_offer(1234567890, 35)

proposal = listing_from_photos(v, ["front.jpg", "back.jpg"], title="Nintendo 3DS", condition="good")
v.publish(photo_ids=proposal["photo_ids"], upload_session_id=proposal["upload_session_id"],
          title="Nintendo 3DS", description="…", price=120, catalog_id=proposal["category"]["id"],
          condition="good", attributes={"video_game_platform": [1265]})

plan = negotiate(v, "<conversation_id>", floor=480)  # dry run; dry_run=False to act

Every method returns a Response (ok, status, data, error_reason) or plain data. Ad-hoc calls: v.get("core" | "edge", path, params) and v.send(method, "core" | "edge", path, body).

How it works

flowchart LR
    subgraph you["Your side"]
        A["MCP client / agent"] -->|stdio| M["vinted-mcp"]
        T["Terminal"] --> C["vinted CLI"]
        P["Python code"] --> L
        M --> L["vinted_mcp.Vinted"]
        C --> L
        L --> AU["automation.py"]
    end
    L --> H["Transport<br/>curl_cffi · Chrome TLS<br/>pacing · retries · 401 refresh"]
    H -->|"core: users, items, uploads,<br/>offers, orders"| W["www.vinted.es/api/v2"]
    H -->|"edge: search, filters, messaging,<br/>notifications, wallet, pricing"| E["api.vinted.es"]
    H -->|"item pages (RSC)"| P2["www.vinted.es/items/…"]
    S[("session.json<br/>or browser cookies")] -.-> H

• Two API hosts. Older REST resources live under www.vinted.<tld>/api/v2, newer services under api.vinted.<tld>. Item details have no JSON endpoint and are parsed from the item page's Next.js data.
• Headers copied from the web app: a constant X-CSRF-Token baked into the JS bundle, X-Anon-Id, Locale. Uploads add X-Upload-Form: true.
• Transport policy. Reads are retried on network errors and 429/5xx (honouring Retry-After); writes are sent once, and a write that dies mid-flight raises UnknownOutcomeError. Requests are paced.
• Every endpoint with its body, verification status and quirks: docs/ENDPOINTS.md. Agent flows: AGENTS.md.

Safety and limits

Configuration

Troubleshooting

Development

python -m venv .venv && .venv/bin/pip install -e '.[test,build]'
.venv/bin/python -m pytest                       # offline: synthetic fixtures, no account, no network
.venv/bin/python -m build && .venv/bin/python scripts/check_package.py dist
.venv/bin/python scripts/build_binary.py         # PyInstaller executables in dist/bin/ + MCP smoke test

CI runs the tests on Python 3.10–3.14, builds the package and the Linux/macOS/Windows executables. Releases: bump VERSION in vinted_mcp/config.py and push a vX.Y.Z tag. See CONTRIBUTING.md.

vinted_mcp/
├── client.py        API client (search, items, chat, offers, listings, account)
├── automation.py    listing from photos, negotiation, relisting
├── http.py          curl_cffi transport, pacing, retries
├── session.py       browser import, login window, token recovery
├── models.py        Item, item-page parsing, offer events
├── mcp_server.py    the MCP tools
└── cli/main.py      the vinted CLI

Status and legal

Experimental and unofficial. The endpoints come from the web application and can change at any time; the offline tests prove protocol handling, not that Vinted still answers the same way.

MIT license. Vinted and its trademarks belong to Vinted UAB; this project is not affiliated with, endorsed by or sponsored by Vinted. The Vinted and Model Context Protocol logos are trademarks of Vinted UAB and of the MCP project; they are shown only to identify the service and protocol this project works with. Use it with your own account and within Vinted's terms.