🛒 finn-seller-mcp

An MCP server that lets Claude (or any MCP client) search and sell on finn.no — Norway's largest marketplace. Send a photo, get a finished Torget ad: description, category, market price, duplicate check, publish.

⭐ If this saves you time, star the repo — it helps others find it.

English · Русский

📖 Table of contents

• ✨ What it does
• 🆚 Why this project
• 🚀 Quick Start
• 💬 Example session
• 🔄 How it works
• 🧰 Tool reference
• 💰 Pricing policy
• 🔁 Duplicate protection
• 🛡️ Safety model
• 🧭 Recon: mapping the site yourself
• ⚙️ Configuration
• 🗂️ Project layout
• 🧪 Development & tests
• 🩺 Troubleshooting
• ❓ FAQ
• 🗺️ Roadmap
• 🤝 Contributing
• ⚖️ Disclaimer
• 📄 License & credits

✨ What it does

🆚 Why this project

Existing finn.no MCP servers are read-only scrapers. This one adds the whole seller side, built on finn.no's internal JSON API (mapped with an included recon tool) rather than brittle form clicking.

🚀 Quick Start

1. Install (needs uv and Python 3.11+)

git clone https://github.com/ml-senior/finn-seller-mcp
cd finn-seller-mcp
uv sync
uv run playwright install chromium

2. Register with your MCP client

{
  "mcpServers": {
    "finn": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/finn-seller-mcp", "run", "finn-seller-mcp"]
    }
  }
}

claude mcp add finn -- uv --directory /absolute/path/to/finn-seller-mcp run finn-seller-mcp

3. Log in once

Ask the assistant to run login (or run the recon script, below). A Chromium window opens on finn.no — you type your e-mail and the one-time code from Vend. The session is stored in a local browser profile and reused from then on.

4. Sell something

"Sell this controller" + 📸 photo

That's it. The assistant checks for duplicates, prepares a private draft on finn.no, shows you the preview and publishes only after you say yes.

[!IMPORTANT] finn.no asks for a one-time BankID identity verification before your first Torget ad goes live. If publish_draft returns bankid_required, open the edit_url it gives you, press Gå videre → Verifiser med BankID, finish it yourself, then ask the assistant to publish again.

💬 Example session

You:     Sell this. [photo of a PS5 controller]
Claude:  ▸ check_duplicate      → nothing similar on your account
         ▸ suggest_price        → median 500 kr from 14 comparable ads
         ▸ create_draft         → photo cleaned (EXIF/GPS removed)
         ▸ push_draft           → private draft created on finn.no
         ▸ suggest_category     → Elektronikk › Spill og konsoll › Tilbehør
         Here's the ad:
           PS5 DualSense kontroller – hvit · Pent brukt · 500 kr · 1 photo
           "Original Sony DualSense trådløs kontroller …"
         Publish?
You:     yes
Claude:  ▸ publish_draft(confirm=true) → live ✅

🔄 How it works

flowchart LR
    U([You + photos]) --> A[Assistant]
    A -->|check_duplicate| D{Already listed?}
    D -- yes --> S[Stop and show matches]
    D -- no --> P[suggest_price<br/>median of comparables]
    P --> C[create_draft<br/>EXIF/GPS strip, resize]
    C --> PU[push_draft<br/>private draft on finn.no]
    PU --> SC[suggest_category<br/>finn.no prediction]
    SC --> PV[Preview to you]
    PV -->|your explicit yes| PB[publish_draft confirm=true]
    PB --> L([Live on finn.no])

Under the hood the server talks to the same JSON endpoints the finn.no web form uses, through a persistent Playwright Chromium profile so requests carry your logged-in session:

sequenceDiagram
    participant M as finn-seller-mcp
    participant F as finn.no
    M->>F: POST create-item … /api/create (adType=recommerce)
    F-->>M: 301 → /recommerce/create/{adId}
    loop each photo
        M->>F: POST /recommerce/create/api/image/{adId} (multipart "image")
        F-->>M: { path: "item/{adId}/{uuid}", width, height }
    end
    M->>F: PUT /recommerce/create/api/item/{adId}  e-tag: W/"rev"  { commit:false, data }
    F-->>M: { state:"draft", violations:[], etag }
    M->>F: POST /recommerce/create/api/predictions/categories/{adId}
    Note over M: user confirms in chat
    M->>F: PUT /recommerce/create/api/item/{adId}  { commit:true, data }
    F-->>M: published — or { requiredVerification:true } → BankID needed

{
  "trade_type": "SELL",
  "category": 65,
  "condition": 3,
  "title": "PS5 DualSense kontroller – hvit",
  "description": "Original Sony DualSense …",
  "price": { "price_amount": 500 },
  "address": { "postalcode": "0150", "country": "NO" },
  "image": [ { "uri": "item/{adId}/{uuid}", "width": 960, "height": 1280, "description": "optional caption" } ]
}

🧰 Tool reference

💰 Pricing policy

The policy is written into the tool descriptions, so any MCP client follows it.

🔁 Duplicate protection

Before creating and again before publishing, every new ad is compared with:

• 🗃️ Local history — every draft/ad made through this server, photos matched by a 64-bit perceptual dHash (survives resizing, re-compression and EXIF stripping; ≤10-bit distance = same picture).
• 🌐 Your finn.no account — all ads in "Mine annonser" in any state, matched by normalized title similarity (≥85 %, or ≥60 % plus a shared photo).

A hit blocks publish_draft. Only confirm_not_duplicate, called after you say "it's a different item", unblocks it.

🛡️ Safety model

🧭 Recon: mapping the site yourself

finn.no can change its internals at any time. scripts/recon.py lets anyone re-map the seller flow in minutes without publishing anything:

uv run python scripts/recon.py --start https://www.finn.no/create-item/start

1. A Chromium window opens with the same profile the server uses — log in.
2. Click through the flows (new ad, photos, price, "Publiser", Mine annonser, edit…). Press the red 📸 Snapshot form button on each form step.
3. Close the window.

⚙️ Configuration

Local data lives in ~/.local/share/finn-mcp/: browser-profile/, drafts/<id>/draft.json + cleaned photos, cache.sqlite.

🗂️ Project layout

finn-seller-mcp/
├── src/finn_mcp/
│   ├── server.py            # FastMCP server, search tools, registers seller tools
│   ├── scraper/             # read-only HTML/JSON-LD scrapers (bap, homes, cars, jobs)
│   ├── backend/             # search backend abstraction
│   └── seller/
│       ├── tools.py         # seller MCP tools
│       ├── api.py           # finn.no seller JSON API client (via Playwright context)
│       ├── browser.py       # persistent Chromium session, interactive login
│       ├── drafts.py        # local draft store + validation
│       ├── photos.py        # EXIF/GPS strip, rotate, resize, HEIC
│       ├── dupes.py         # perceptual-hash + title duplicate detection
│       ├── pricing.py       # market-price median with outlier removal
│       └── selectors.py     # every site-specific URL/selector in one place
├── scripts/recon.py         # site recorder with publish blocking
├── tests/                   # fixtures-based tests (no network)
├── RECON.md                 # what we know about finn.no internals
└── docs/                    # translations, assets

🧪 Development & tests

uv sync
uv run pytest -q          # offline: HTML fixtures, pricing, duplicates

Tests never hit finn.no. For end-to-end work, point FINN_BASE_URL at a mock server that replays shapes from RECON.md.

🩺 Troubleshooting

❓ FAQ

Is there an official finn.no API for this? Not for private sellers. FINN's import APIs are B2B (jobs, real estate, dealers) and require a contract. This project uses the same internal endpoints as the finn.no website, with your own session.

Does the AI see my password? There is no password — login is e-mail + one-time code, and you type both yourself in a real browser window.

Can it publish without asking? No. publish_draft without confirm=true only returns a preview, and the tool contract requires your explicit "yes".

Which categories work? All Torget leaf categories. Category-specific extra fields can be passed via attributes.

Does it work for cars / real estate? Search: yes. Selling: Torget only for now.

🗺️ Roadmap

• Read-only search, listings, saved searches
• Login via persistent browser profile
• Create / push / publish Torget ads, photo upload
• Category prediction, market price, duplicate guard
• Mine annonser + generic ad actions
• Recon tool with publish blocking
• "Gi bort" (give away) trade type
• Fiks ferdig (shipping) fields
• Mark sold / deactivate / renew on live ads (action names pending recon)
• Buyer messages
• Full category tree export
• Price from Klarna Prisguiden (new-price ceiling)

🤝 Contributing

PRs welcome — see CONTRIBUTING.md. If finn.no changed something, run the recon script and attach the redacted endpoints.md (never the private/ folder).

⚖️ Disclaimer

Independent open-source project, not affiliated with or endorsed by FINN.no / Vend Marketplaces. It automates your own account through finn.no's web endpoints; you are responsible for complying with finn.no's terms of use. Keep usage personal and moderate — no bulk listing, no scraping at scale.

📄 License & credits

MIT © 2026 ml-senior

Search/scraper layer based on aHk-coder/finn-mcp (MIT). Condition and category code tables adapted from viktorfa/finn_mcp (MIT).