wallapop-mcp 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wallapop_mcp-0.2.0/.gitignore +14 -0
- wallapop_mcp-0.2.0/AGENTS.md +108 -0
- wallapop_mcp-0.2.0/CONTRIBUTING.md +27 -0
- wallapop_mcp-0.2.0/CREDITS.md +5 -0
- wallapop_mcp-0.2.0/LICENSE +22 -0
- wallapop_mcp-0.2.0/PKG-INFO +153 -0
- wallapop_mcp-0.2.0/README.md +114 -0
- wallapop_mcp-0.2.0/docs/API.md +222 -0
- wallapop_mcp-0.2.0/docs/ENDPOINTS.md +985 -0
- wallapop_mcp-0.2.0/docs/USAGE.md +501 -0
- wallapop_mcp-0.2.0/docs/categories.json +5128 -0
- wallapop_mcp-0.2.0/docs/multi-photo-upload.md +102 -0
- wallapop_mcp-0.2.0/packaging/entry_cli.py +5 -0
- wallapop_mcp-0.2.0/packaging/entry_mcp.py +5 -0
- wallapop_mcp-0.2.0/packaging/wallapop.spec +43 -0
- wallapop_mcp-0.2.0/pyproject.toml +76 -0
- wallapop_mcp-0.2.0/scripts/build_binary.py +78 -0
- wallapop_mcp-0.2.0/scripts/check_package.py +21 -0
- wallapop_mcp-0.2.0/tests/test_client.py +1937 -0
- wallapop_mcp-0.2.0/tests/test_config.py +173 -0
- wallapop_mcp-0.2.0/tests/test_http.py +396 -0
- wallapop_mcp-0.2.0/tests/test_ids.py +35 -0
- wallapop_mcp-0.2.0/tests/test_mcp_server.py +92 -0
- wallapop_mcp-0.2.0/tests/test_models.py +344 -0
- wallapop_mcp-0.2.0/tests/test_session.py +108 -0
- wallapop_mcp-0.2.0/tests/test_tokens.py +168 -0
- wallapop_mcp-0.2.0/wallapop_mcp/__init__.py +65 -0
- wallapop_mcp-0.2.0/wallapop_mcp/cli/__init__.py +5 -0
- wallapop_mcp-0.2.0/wallapop_mcp/cli/commands.py +1203 -0
- wallapop_mcp-0.2.0/wallapop_mcp/cli/main.py +270 -0
- wallapop_mcp-0.2.0/wallapop_mcp/cli/output.py +208 -0
- wallapop_mcp-0.2.0/wallapop_mcp/client.py +1884 -0
- wallapop_mcp-0.2.0/wallapop_mcp/config.py +297 -0
- wallapop_mcp-0.2.0/wallapop_mcp/http.py +457 -0
- wallapop_mcp-0.2.0/wallapop_mcp/ids.py +38 -0
- wallapop_mcp-0.2.0/wallapop_mcp/mcp_server.py +543 -0
- wallapop_mcp-0.2.0/wallapop_mcp/models.py +568 -0
- wallapop_mcp-0.2.0/wallapop_mcp/publish.py +221 -0
- wallapop_mcp-0.2.0/wallapop_mcp/py.typed +0 -0
- wallapop_mcp-0.2.0/wallapop_mcp/session.py +92 -0
- wallapop_mcp-0.2.0/wallapop_mcp/tokens.py +54 -0
- wallapop_mcp-0.2.0/wallapop_mcp/weblogin.py +82 -0
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# AGENTS.md — driving wallapop-mcp from an AI agent
|
|
2
|
+
|
|
3
|
+
MCP server + CLI + Python library for Wallapop, **one codebase**
|
|
4
|
+
(`pip install wallapop-mcp`): the MCP server and the CLI both call the
|
|
5
|
+
`wallapop_mcp` package, so a fix lands once. Two jobs:
|
|
6
|
+
|
|
7
|
+
- **[Flow A — buy & negotiate](#flow-a--buy--negotiate)**: search, make offers, haggle a price down.
|
|
8
|
+
- **[Flow B — sell](#flow-b--sell)**: publish, edit, reply to buyers, accept/decline offers.
|
|
9
|
+
|
|
10
|
+
Read **[Login](#login--session)** first, then the flow you need, then the
|
|
11
|
+
**[tool reference](#mcp-tool-reference)**.
|
|
12
|
+
|
|
13
|
+
## Interfaces
|
|
14
|
+
|
|
15
|
+
| | MCP server | CLI | Library |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| Entry | `wallapop-mcp` / `python -m wallapop_mcp.mcp_server` | `wallapop` | `import wallapop_mcp` |
|
|
18
|
+
| Transport | stdio MCP (tools) | shell commands | Python calls |
|
|
19
|
+
| Writes | need `--allow-writes` | always available | always available |
|
|
20
|
+
|
|
21
|
+
All three share `wallapop_mcp`. Public reads (search, item, seller, categories)
|
|
22
|
+
need **no account**; inbox, offers, purchases/sales and every write need a
|
|
23
|
+
**session**. Ad-hoc API call:
|
|
24
|
+
`client, _ = wallapop_mcp.build_client(); client._authed("GET"|"PUT"|…, path, body=?, extra_headers=?)`.
|
|
25
|
+
|
|
26
|
+
## Login / session
|
|
27
|
+
|
|
28
|
+
The tools never log in; you give them an existing session (stored outside the
|
|
29
|
+
repo in `~/.config/wallapop-mcp/`). Create one with the CLI:
|
|
30
|
+
|
|
31
|
+
| Method | Command | Use when |
|
|
32
|
+
|---|---|---|
|
|
33
|
+
| Email + password | `wallapop login you@mail.com` (prompts) | normal account |
|
|
34
|
+
| Browser wizard | `wallapop login --wizard` (needs `pip install 'wallapop-mcp[browser]' && playwright install chromium`) | Google login / browser-only session |
|
|
35
|
+
| Import Firefox | `wallapop login --browser firefox` | already logged in to wallapop.com in Firefox |
|
|
36
|
+
| Paste cookies | `wallapop login --cookies-file cookies.txt` | any browser (copy the `Cookie:` header from DevTools) |
|
|
37
|
+
|
|
38
|
+
**Headless agents:** `login you@mail.com` and `--wizard` need a TTY/GUI. Use
|
|
39
|
+
**`--cookies-file`** or set **`WALLAPOP_ACCESS_TOKEN`** (+ optional
|
|
40
|
+
`WALLAPOP_REFRESH_TOKEN`). The MCP server takes `--session <dir|file>` (default
|
|
41
|
+
`~/.config/wallapop-mcp`, or `WALLAPOP_CONFIG_DIR`) or the same env var; writes need `--allow-writes`.
|
|
42
|
+
Check state with no network: `wallapop session` / the `session_status` tool.
|
|
43
|
+
|
|
44
|
+
## Flow A — buy & negotiate
|
|
45
|
+
|
|
46
|
+
1. **Search** — `wallapop search "nintendo switch" --city galicia --max-price 200 --order price_low_to_high`
|
|
47
|
+
(MCP: `search`; anchor precisely with `latitude`+`longitude`). `wallapop deals "<kw>"` ranks bargains vs the median.
|
|
48
|
+
2. **Inspect** — `wallapop show <item-id|url|slug>` (`get_item`) and `wallapop show <seller-id>` (`get_seller`) before committing.
|
|
49
|
+
3. **Offer** — `wallapop offer <item> --price 30` (MCP `send_offer`; `send_offer` does not buy or pay).
|
|
50
|
+
4. **Negotiate** — watch with `wallapop replies --conversation <id>` (`get_conversation`) and `wallapop offer status [<conv>]` (`get_offer_status`); respond with `wallapop offer accept|decline|counter <offer_id> [--price 34]` (`respond_offer` / `counter_offer`).
|
|
51
|
+
5. **Close** — accept at the agreed price; Wallapop then drives checkout/shipping (no payment step here).
|
|
52
|
+
|
|
53
|
+
Anchor your first offer below target and move up in small steps; `get_offer_status` shows the current amount in play.
|
|
54
|
+
|
|
55
|
+
## Flow B — sell
|
|
56
|
+
|
|
57
|
+
1. **Publish** — `wallapop publish <photos_dir> --summary "<title ≤50>" --price 42 --condition as_good_as_new [--brand Nulea --model M512]`.
|
|
58
|
+
Library/MCP let you set the category: `client.publish(photo_paths=[…], title=…, price=42, category_leaf_id="10311", condition="as_good_as_new", description=…)` / `publish_item`. **Use the right `category_leaf_id`** (mice `10311`, keyboards `10312`; find it from a comparable item's `taxonomy[-1].id`). `color` is optional — only pass it where the category has a color attribute.
|
|
59
|
+
2. **Edit** — `wallapop edit <item> --price 169 --title "…"` (`edit_item`). Lowering the price notifies users who favourited the item. Success is silent.
|
|
60
|
+
3. **Reply to a buyer** (seller side) — reply **by conversation id**; messaging by `item_id` 403s on your own item: `wallapop message --conversation <id> --text "…"` (MCP `send_message` with `conversation_id`).
|
|
61
|
+
4. **Handle offers** — `wallapop offer status`, then `wallapop offer accept <offer_id>` / `decline` / `counter --price 34`. Accept commits the sale (buyer then pays).
|
|
62
|
+
5. **Lifecycle** — `wallapop reserve|sold|delete <item>` (`reserve_item` / `mark_sold` / `delete_item`). A public listing URL is the slug (`.../item/<slug>-<numericid>`), not the bare internal id (which 404s in a browser).
|
|
63
|
+
|
|
64
|
+
## MCP tool reference
|
|
65
|
+
|
|
66
|
+
30 tools. The 13 writes appear only with `--allow-writes`.
|
|
67
|
+
|
|
68
|
+
**Reads:** `session_status`, `search`, `suggest`, `get_item`, `get_seller`,
|
|
69
|
+
`seller_items`, `list_categories`, `list_inbox`, `get_conversation`,
|
|
70
|
+
`unread_count`, `list_purchases` (`tab`), `list_sales` (`tab`),
|
|
71
|
+
`get_offer_constraints`, `get_offer_status`, `list_favorites`,
|
|
72
|
+
`saved_search_hits`, `check_saved_search`.
|
|
73
|
+
|
|
74
|
+
**Writes:** `set_favorite`, `send_message` (`item_id` **or** `conversation_id`),
|
|
75
|
+
`send_offer`, `respond_offer`, `counter_offer`, `publish_item`, `edit_item`,
|
|
76
|
+
`reserve_item`, `mark_sold`, `pause_item`, `delete_item`, `save_search`,
|
|
77
|
+
`remove_saved_search`.
|
|
78
|
+
|
|
79
|
+
**Sniping / alerts:** `save_search` stores a search (same filters as `search`)
|
|
80
|
+
so Wallapop notifies new matches; `saved_search_hits` returns the unseen-match
|
|
81
|
+
counter, `check_saved_search` finds the id of an existing one and
|
|
82
|
+
`remove_saved_search` deletes it. CLI: `wallapop alert save|check|hits|remove`.
|
|
83
|
+
|
|
84
|
+
Results are JSON. Writes may be partial or unknown — inspect the returned state
|
|
85
|
+
before retrying; there is no checkout or payment.
|
|
86
|
+
|
|
87
|
+
## API quirks (handled by the library — good to know)
|
|
88
|
+
|
|
89
|
+
- **`publish` + `color`.** Color-less categories (e.g. mice `10311`) answer `400
|
|
90
|
+
INVALID_ATTRIBUTE` when `color` is present, even empty. `publish` omits it when
|
|
91
|
+
empty; pass a color only where the category needs one.
|
|
92
|
+
- **`edit` state read.** The versioned edit GET (`Accept:
|
|
93
|
+
application/vnd.upload-v2+json`) now returns `406`; `edit_item` reads a plain
|
|
94
|
+
`GET /items/<id>` and maps the live shape (attributes under `type_attributes`,
|
|
95
|
+
category under `taxonomy[-1].id`, price under `price.cash.amount`,
|
|
96
|
+
`description` as `{"original": …}` — re-sent as a plain string).
|
|
97
|
+
- **Seller replies.** `send_message`/`ensure_conversation` POST a buyer→seller
|
|
98
|
+
conversation and 403 on your own item; `reply_to_conversation` (used by
|
|
99
|
+
`send_message` + `conversation_id`) publishes straight to the existing channel.
|
|
100
|
+
- **No "offer to favouriters".** Only buyer→seller offers exist; the API exposes
|
|
101
|
+
the favourite count, never who favourited. Lowering the price is the nudge.
|
|
102
|
+
|
|
103
|
+
## File map
|
|
104
|
+
|
|
105
|
+
- `wallapop_mcp/client.py` — API client (`search`, `item`, `publish`, `edit_item`, `send_offer`, `reply_to_conversation`, …).
|
|
106
|
+
- `wallapop_mcp/mcp_server.py` — the MCP server (all tools delegate here).
|
|
107
|
+
- `wallapop_mcp/cli/` — the `wallapop` CLI. `wallapop_mcp/{config,http,models,ids,session}.py` — supporting modules.
|
|
108
|
+
- `tests/` — pytest suite (library, CLI, MCP). `docs/ENDPOINTS.md` — raw endpoint research.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Keep changes focused and describe the observable behavior they fix. Bug reports should include the command or MCP tool, version, sanitized input, expected result and actual result. Never include session files, tokens, cookies or private messages.
|
|
4
|
+
|
|
5
|
+
## Checks
|
|
6
|
+
|
|
7
|
+
Python 3.10+.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
python3 -m venv .venv
|
|
11
|
+
.venv/bin/pip install -e '.[test,build]'
|
|
12
|
+
.venv/bin/python -m pytest
|
|
13
|
+
.venv/bin/python -m build && .venv/bin/python scripts/check_package.py dist
|
|
14
|
+
.venv/bin/python scripts/build_binary.py # PyInstaller executables in dist/bin/
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Releases: bump `VERSION` in `wallapop_mcp/config.py`, then push a `vX.Y.Z` tag.
|
|
18
|
+
The release workflow tests, publishes to PyPI (trusted publishing) and attaches
|
|
19
|
+
Linux/macOS/Windows executables to the GitHub release.
|
|
20
|
+
|
|
21
|
+
Add regression tests for changed API behavior using local HTTP servers or synthetic fixtures. The regular test suite must not contact Wallapop or read a developer's session. Label any manually verified live behavior separately.
|
|
22
|
+
|
|
23
|
+
Keep stdout reserved for the MCP server's stdio transport. Bound new network responses and outputs. Treat mutations as non-retryable unless the upstream service provides a verified idempotency mechanism. Preserve created resource IDs after partial failures.
|
|
24
|
+
|
|
25
|
+
Use the endpoint research as evidence, not as proof that an endpoint still works. Document agent-facing changes in [AGENTS.md](AGENTS.md) and the library in [docs/API.md](docs/API.md); keep credits intact.
|
|
26
|
+
|
|
27
|
+
AI-assisted changes are welcome when reviewed and tested by the contributor. Do not commit agent transcripts, private prompts, worktree paths or generated planning logs.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Credits
|
|
2
|
+
|
|
3
|
+
This project's Python CLI, library, endpoint research, data models, authentication and messaging flows, documentation and tests were created by [figurophobia](https://github.com/figurophobia). Its Git history and author attribution are retained.
|
|
4
|
+
|
|
5
|
+
The MCP server reuses the same `wallapop_mcp` client as the CLI. Dependency licenses remain with their respective authors.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 figurophobia
|
|
4
|
+
Copyright (c) 2026 Wallapop MCP contributors
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: wallapop-mcp
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: MCP server for Wallapop: search, deals, offers, chat, saved searches and listing management for AI agents. Also ships a CLI and a typed Python client.
|
|
5
|
+
Project-URL: Homepage, https://github.com/figurophobia/wallapop-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/figurophobia/wallapop-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/figurophobia/wallapop-mcp/issues
|
|
8
|
+
Project-URL: Documentation, https://github.com/figurophobia/wallapop-mcp/blob/main/AGENTS.md
|
|
9
|
+
Author: figurophobia
|
|
10
|
+
Maintainer: jrrome
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: ai-agents,api,chat,cli,client,mcp,model-context-protocol,offers,wallapop
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
25
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
26
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
27
|
+
Classifier: Typing :: Typed
|
|
28
|
+
Requires-Python: >=3.10
|
|
29
|
+
Requires-Dist: mcp>=2
|
|
30
|
+
Provides-Extra: browser
|
|
31
|
+
Requires-Dist: playwright; extra == 'browser'
|
|
32
|
+
Provides-Extra: build
|
|
33
|
+
Requires-Dist: build; extra == 'build'
|
|
34
|
+
Requires-Dist: pyinstaller>=6; extra == 'build'
|
|
35
|
+
Requires-Dist: twine; extra == 'build'
|
|
36
|
+
Provides-Extra: test
|
|
37
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
|
|
40
|
+
# wallapop-mcp
|
|
41
|
+
|
|
42
|
+
An [MCP](https://modelcontextprotocol.io) server for Wallapop, written in pure
|
|
43
|
+
Python: let an AI agent search listings, spot deals, negotiate offers, chat with
|
|
44
|
+
buyers and sellers, keep saved-search alerts and manage your own listings — no
|
|
45
|
+
browser required for the core workflows.
|
|
46
|
+
|
|
47
|
+
The same package ships the `wallapop` CLI and the typed `wallapop_mcp` Python client.
|
|
48
|
+
All three share one API client, so a fix lands in one place.
|
|
49
|
+
|
|
50
|
+
## Install
|
|
51
|
+
|
|
52
|
+
Python 3.10+.
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
pip install wallapop-mcp # or: uvx wallapop-mcp / pipx install wallapop-mcp
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Prefer no Python at all? Download the standalone `wallapop-mcp` executable
|
|
59
|
+
(Linux, macOS, Windows; built with PyInstaller) from the
|
|
60
|
+
[releases page](https://github.com/figurophobia/wallapop-mcp/releases).
|
|
61
|
+
|
|
62
|
+
## Use it from an MCP client
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
{
|
|
66
|
+
"mcpServers": {
|
|
67
|
+
"wallapop": {
|
|
68
|
+
"command": "wallapop-mcp",
|
|
69
|
+
"args": ["--allow-writes"]
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Claude Code: `claude mcp add wallapop -- wallapop-mcp --allow-writes`.
|
|
76
|
+
|
|
77
|
+
- **Reads work without an account** (search, suggestions, item details,
|
|
78
|
+
sellers, categories). Inbox, offers, favorites, purchases/sales, saved
|
|
79
|
+
searches and every write need a session.
|
|
80
|
+
- **Writes are hidden unless `--allow-writes`** is passed.
|
|
81
|
+
- Session: `--session <dir|file>` (default `~/.config/wallapop-mcp`, override
|
|
82
|
+
with `WALLAPOP_CONFIG_DIR`) or `WALLAPOP_ACCESS_TOKEN` (+ optional
|
|
83
|
+
`WALLAPOP_REFRESH_TOKEN`).
|
|
84
|
+
|
|
85
|
+
30 tools (17 read, 13 write): search & deals, item/seller lookup, inbox and
|
|
86
|
+
conversations, offers (send, accept, decline, counter), favorites, saved-search
|
|
87
|
+
alerts, publish/edit/reserve/sold/pause/delete listings. Full reference and
|
|
88
|
+
agent flows in [AGENTS.md](https://github.com/figurophobia/wallapop-mcp/blob/main/AGENTS.md).
|
|
89
|
+
|
|
90
|
+
## Log in
|
|
91
|
+
|
|
92
|
+
The server never logs in by itself; create a session once with the CLI:
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
wallapop login you@mail.com # email + password (prompts)
|
|
96
|
+
wallapop login --browser firefox # import an existing Firefox session
|
|
97
|
+
wallapop login --cookies-file cookies.txt # paste the Cookie: header from DevTools
|
|
98
|
+
wallapop session # check status, offline
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
For the Google/browser wizard: `pip install 'wallapop-mcp[browser]' && playwright install chromium`,
|
|
102
|
+
then `wallapop login --wizard`. Credentials live in `~/.config/wallapop-mcp/`,
|
|
103
|
+
outside any repository; never paste them into prompts or issues.
|
|
104
|
+
|
|
105
|
+
## CLI
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
wallapop search "nintendo switch" --city galicia --max-price 200
|
|
109
|
+
wallapop deals "nintendo switch" # bargains vs. the median price
|
|
110
|
+
wallapop show <item-url-or-id>
|
|
111
|
+
wallapop offer <item> --price 30
|
|
112
|
+
wallapop alert save "switch 2" --max-price 300 # saved search (alert)
|
|
113
|
+
wallapop publish <photos_dir> --summary "..." --price 42 --condition as_good_as_new
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
See [docs/USAGE.md](https://github.com/figurophobia/wallapop-mcp/blob/main/docs/USAGE.md).
|
|
117
|
+
|
|
118
|
+
## Library
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
from wallapop_mcp import Wallapop, build_client
|
|
122
|
+
|
|
123
|
+
public = Wallapop()
|
|
124
|
+
for item in public.search("nintendo switch", pages=1):
|
|
125
|
+
print(item.price, item.title, item.url)
|
|
126
|
+
|
|
127
|
+
client, _ = build_client() # signed-in client; raises SessionError if not logged in
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
See [docs/API.md](https://github.com/figurophobia/wallapop-mcp/blob/main/docs/API.md).
|
|
131
|
+
|
|
132
|
+
## Develop
|
|
133
|
+
|
|
134
|
+
```sh
|
|
135
|
+
python3 -m venv .venv
|
|
136
|
+
.venv/bin/pip install -e '.[test,build]'
|
|
137
|
+
.venv/bin/python -m pytest # offline: local fixtures, no account
|
|
138
|
+
.venv/bin/python -m build # sdist + wheel in dist/
|
|
139
|
+
.venv/bin/python scripts/build_binary.py # PyInstaller executables in dist/bin/
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Releasing is described in [CONTRIBUTING.md](https://github.com/figurophobia/wallapop-mcp/blob/main/CONTRIBUTING.md).
|
|
143
|
+
|
|
144
|
+
## Status
|
|
145
|
+
|
|
146
|
+
Experimental, unofficial integration. The endpoints are derived from the web
|
|
147
|
+
application and can change or reject non-browser clients. Offline tests cover
|
|
148
|
+
protocol behaviour and known response shapes; they do not establish current live
|
|
149
|
+
compatibility. Writes may have partial or unknown outcomes; there is no checkout
|
|
150
|
+
or payment.
|
|
151
|
+
|
|
152
|
+
MIT license. Wallapop and its trademarks belong to their respective owners; this
|
|
153
|
+
project is not affiliated with Wallapop. See [CREDITS.md](https://github.com/figurophobia/wallapop-mcp/blob/main/CREDITS.md).
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# wallapop-mcp
|
|
2
|
+
|
|
3
|
+
An [MCP](https://modelcontextprotocol.io) server for Wallapop, written in pure
|
|
4
|
+
Python: let an AI agent search listings, spot deals, negotiate offers, chat with
|
|
5
|
+
buyers and sellers, keep saved-search alerts and manage your own listings — no
|
|
6
|
+
browser required for the core workflows.
|
|
7
|
+
|
|
8
|
+
The same package ships the `wallapop` CLI and the typed `wallapop_mcp` Python client.
|
|
9
|
+
All three share one API client, so a fix lands in one place.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
Python 3.10+.
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pip install wallapop-mcp # or: uvx wallapop-mcp / pipx install wallapop-mcp
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Prefer no Python at all? Download the standalone `wallapop-mcp` executable
|
|
20
|
+
(Linux, macOS, Windows; built with PyInstaller) from the
|
|
21
|
+
[releases page](https://github.com/figurophobia/wallapop-mcp/releases).
|
|
22
|
+
|
|
23
|
+
## Use it from an MCP client
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"mcpServers": {
|
|
28
|
+
"wallapop": {
|
|
29
|
+
"command": "wallapop-mcp",
|
|
30
|
+
"args": ["--allow-writes"]
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Claude Code: `claude mcp add wallapop -- wallapop-mcp --allow-writes`.
|
|
37
|
+
|
|
38
|
+
- **Reads work without an account** (search, suggestions, item details,
|
|
39
|
+
sellers, categories). Inbox, offers, favorites, purchases/sales, saved
|
|
40
|
+
searches and every write need a session.
|
|
41
|
+
- **Writes are hidden unless `--allow-writes`** is passed.
|
|
42
|
+
- Session: `--session <dir|file>` (default `~/.config/wallapop-mcp`, override
|
|
43
|
+
with `WALLAPOP_CONFIG_DIR`) or `WALLAPOP_ACCESS_TOKEN` (+ optional
|
|
44
|
+
`WALLAPOP_REFRESH_TOKEN`).
|
|
45
|
+
|
|
46
|
+
30 tools (17 read, 13 write): search & deals, item/seller lookup, inbox and
|
|
47
|
+
conversations, offers (send, accept, decline, counter), favorites, saved-search
|
|
48
|
+
alerts, publish/edit/reserve/sold/pause/delete listings. Full reference and
|
|
49
|
+
agent flows in [AGENTS.md](https://github.com/figurophobia/wallapop-mcp/blob/main/AGENTS.md).
|
|
50
|
+
|
|
51
|
+
## Log in
|
|
52
|
+
|
|
53
|
+
The server never logs in by itself; create a session once with the CLI:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
wallapop login you@mail.com # email + password (prompts)
|
|
57
|
+
wallapop login --browser firefox # import an existing Firefox session
|
|
58
|
+
wallapop login --cookies-file cookies.txt # paste the Cookie: header from DevTools
|
|
59
|
+
wallapop session # check status, offline
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
For the Google/browser wizard: `pip install 'wallapop-mcp[browser]' && playwright install chromium`,
|
|
63
|
+
then `wallapop login --wizard`. Credentials live in `~/.config/wallapop-mcp/`,
|
|
64
|
+
outside any repository; never paste them into prompts or issues.
|
|
65
|
+
|
|
66
|
+
## CLI
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
wallapop search "nintendo switch" --city galicia --max-price 200
|
|
70
|
+
wallapop deals "nintendo switch" # bargains vs. the median price
|
|
71
|
+
wallapop show <item-url-or-id>
|
|
72
|
+
wallapop offer <item> --price 30
|
|
73
|
+
wallapop alert save "switch 2" --max-price 300 # saved search (alert)
|
|
74
|
+
wallapop publish <photos_dir> --summary "..." --price 42 --condition as_good_as_new
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
See [docs/USAGE.md](https://github.com/figurophobia/wallapop-mcp/blob/main/docs/USAGE.md).
|
|
78
|
+
|
|
79
|
+
## Library
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from wallapop_mcp import Wallapop, build_client
|
|
83
|
+
|
|
84
|
+
public = Wallapop()
|
|
85
|
+
for item in public.search("nintendo switch", pages=1):
|
|
86
|
+
print(item.price, item.title, item.url)
|
|
87
|
+
|
|
88
|
+
client, _ = build_client() # signed-in client; raises SessionError if not logged in
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
See [docs/API.md](https://github.com/figurophobia/wallapop-mcp/blob/main/docs/API.md).
|
|
92
|
+
|
|
93
|
+
## Develop
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
python3 -m venv .venv
|
|
97
|
+
.venv/bin/pip install -e '.[test,build]'
|
|
98
|
+
.venv/bin/python -m pytest # offline: local fixtures, no account
|
|
99
|
+
.venv/bin/python -m build # sdist + wheel in dist/
|
|
100
|
+
.venv/bin/python scripts/build_binary.py # PyInstaller executables in dist/bin/
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Releasing is described in [CONTRIBUTING.md](https://github.com/figurophobia/wallapop-mcp/blob/main/CONTRIBUTING.md).
|
|
104
|
+
|
|
105
|
+
## Status
|
|
106
|
+
|
|
107
|
+
Experimental, unofficial integration. The endpoints are derived from the web
|
|
108
|
+
application and can change or reject non-browser clients. Offline tests cover
|
|
109
|
+
protocol behaviour and known response shapes; they do not establish current live
|
|
110
|
+
compatibility. Writes may have partial or unknown outcomes; there is no checkout
|
|
111
|
+
or payment.
|
|
112
|
+
|
|
113
|
+
MIT license. Wallapop and its trademarks belong to their respective owners; this
|
|
114
|
+
project is not affiliated with Wallapop. See [CREDITS.md](https://github.com/figurophobia/wallapop-mcp/blob/main/CREDITS.md).
|