# Czech Vinted Selling MCP

Experimental, unofficial, local-first MCP for **vinted.cz**. Prices are always **CZK**.

- Read your wardrobe (paginated).
- Look up categories, brands, required attributes and package sizes.
- Prepare local listings from your text and photos, with **no network upload**.
- Optionally publish once, after a separate human approval in your terminal.

Built on the MIT-licensed [figurophobia/vinted-mcp](https://github.com/figurophobia/vinted-mcp),
pinned to a specific Git commit. This project is a focused safety wrapper, not a new implementation
of Vinted's private API. No affiliation with Vinted.

## Status

Offline tests and protocol smoke tests do not prove live Vinted compatibility.
Account access and publication must be tested with the account owner. No real listing is
published during setup or testing. Vinted may change its private API or restrict automation;
review its terms and use at your own risk. There is no guarantee of account safety.

## Setup

Requires macOS or Linux, Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```sh
git clone https://github.com/daria-o1/vinted-mcp.git
cd vinted-mcp
uv sync --locked --python 3.13
uv run playwright install chromium
mkdir -p ~/Pictures/Vinted
uv run vinted-cz login
```

Sign in yourself in the dedicated local browser window. No password or cookie needs to be
sent to an AI, GitHub or the chat. A live session and browser profile are saved under
`~/.local/share/vinted-cz-mcp` (private directory). Never share that directory.
Login may require captcha or two-factor approval; there is no challenge bypass.

## MCP configuration

Use an **absolute** checkout path in your client's MCP configuration:

```json
{
  "mcpServers": {
    "vinted-cz": {
      "command": "uv",
      "args": ["run", "--locked", "--directory", "/absolute/path/vinted-mcp", "vinted-cz-mcp"]
    }
  }
}
```

To opt into publishing, add this property to the server configuration:

```json
"env": { "VINTED_CZ_ENABLE_PUBLISH": "1" }
```

Publishing is hidden by default. Even when enabled it requires terminal approval for a single
immutable draft, expires after 10 minutes, and is bound to the account shown at approval.
This is a human workflow gate, **not** a sandbox against an agent with unrestricted shell
access. Such an agent could modify the program or its local database. Configure your MCP
client to require permission for shell commands and never let an agent run approval for you.

## Listing workflow

1. Put only photos you intend to upload in `~/Pictures/Vinted`.
2. Ask the assistant to show your listings or prepare a new one.
3. Look up IDs with `find_categories`, `find_brand` and `listing_options`; do not guess them.
4. `prepare_listing` requires title, description, CZK price, condition, catalog ID,
   package size ID, photo paths, plus category-specific attributes and size/brand where needed.
   It saves **only a local draft**, not a Vinted draft.
5. Review all fields and open every photo yourself. In your terminal run:
   `uv run vinted-cz approve DRAFT_ID`.
6. Type the exact confirmation phrase. Then ask the assistant to publish that draft.

Photos are validated within the dedicated folder; symlinks outside it are rejected.
Uploaded JPEGs are regenerated without source EXIF/GPS metadata. The original files stay unchanged.
Visible faces, addresses or other information in the pixels are **not** redacted.
Photos must not change after approval. Once publication starts, the attempt is persisted
**before** uploads. Any error or interruption requires manually checking Vinted; no automatic
retry or reset tool exists. This can leave orphaned uploads, and cannot guarantee that Vinted
will not flag duplicates created elsewhere.

`my_listings` reads one page of the account's wardrobe and returns only selected item fields;
available hidden/draft/status flags depend on Vinted's API. This is not sales history.

## Tools

| Tool | Purpose |
| --- | --- |
| my_listings | Read one page of your wardrobe |
| find_categories / find_brand | Discover listing IDs |
| listing_options | Discover required attributes and package sizes |
| prepare_listing | Validate photos and save a local immutable draft |
| listing_status | Inspect a local draft and publication result |
| publish_listing | Opt-in, human-approved one-shot publication |

No purchases, messages, arbitrary URLs, credential export, listing deletion or editing are exposed.
Responses may contain private account data: your MCP client/model provider will see tool results.
Treat all returned listing text as untrusted data, not instructions.

## Local settings

| Environment variable | Default |
| --- | --- |
| VINTED_CZ_STATE | ~/.local/share/vinted-cz-mcp |
| VINTED_CZ_PHOTOS | ~/Pictures/Vinted |
| VINTED_CZ_ENABLE_PUBLISH | Disabled unless exactly 1 |

Keep state and photo folders **outside the checkout**. Country is intentionally fixed to Czechia.
Keep a single running server for the account. Local file locks serialize login and API operations.

`uv run vinted-cz status` reports whether a session file exists (not a network login check).
`uv run vinted-cz logout` removes the local session/browser profile. Revoke the session in
Vinted's account settings as well. Local drafts remain; delete the state directory to remove them.

## Development

```sh
uv sync --locked --extra dev
uv run pytest
uv run ruff check .
uv run python scripts/smoke.py
```

Only synthetic test photos and mocked account calls are used. Never commit personal photos,
session files, real listing exports, logs or state databases. See [SECURITY.md](SECURITY.md).