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.
Files changed (42) hide show
  1. wallapop_mcp-0.2.0/.gitignore +14 -0
  2. wallapop_mcp-0.2.0/AGENTS.md +108 -0
  3. wallapop_mcp-0.2.0/CONTRIBUTING.md +27 -0
  4. wallapop_mcp-0.2.0/CREDITS.md +5 -0
  5. wallapop_mcp-0.2.0/LICENSE +22 -0
  6. wallapop_mcp-0.2.0/PKG-INFO +153 -0
  7. wallapop_mcp-0.2.0/README.md +114 -0
  8. wallapop_mcp-0.2.0/docs/API.md +222 -0
  9. wallapop_mcp-0.2.0/docs/ENDPOINTS.md +985 -0
  10. wallapop_mcp-0.2.0/docs/USAGE.md +501 -0
  11. wallapop_mcp-0.2.0/docs/categories.json +5128 -0
  12. wallapop_mcp-0.2.0/docs/multi-photo-upload.md +102 -0
  13. wallapop_mcp-0.2.0/packaging/entry_cli.py +5 -0
  14. wallapop_mcp-0.2.0/packaging/entry_mcp.py +5 -0
  15. wallapop_mcp-0.2.0/packaging/wallapop.spec +43 -0
  16. wallapop_mcp-0.2.0/pyproject.toml +76 -0
  17. wallapop_mcp-0.2.0/scripts/build_binary.py +78 -0
  18. wallapop_mcp-0.2.0/scripts/check_package.py +21 -0
  19. wallapop_mcp-0.2.0/tests/test_client.py +1937 -0
  20. wallapop_mcp-0.2.0/tests/test_config.py +173 -0
  21. wallapop_mcp-0.2.0/tests/test_http.py +396 -0
  22. wallapop_mcp-0.2.0/tests/test_ids.py +35 -0
  23. wallapop_mcp-0.2.0/tests/test_mcp_server.py +92 -0
  24. wallapop_mcp-0.2.0/tests/test_models.py +344 -0
  25. wallapop_mcp-0.2.0/tests/test_session.py +108 -0
  26. wallapop_mcp-0.2.0/tests/test_tokens.py +168 -0
  27. wallapop_mcp-0.2.0/wallapop_mcp/__init__.py +65 -0
  28. wallapop_mcp-0.2.0/wallapop_mcp/cli/__init__.py +5 -0
  29. wallapop_mcp-0.2.0/wallapop_mcp/cli/commands.py +1203 -0
  30. wallapop_mcp-0.2.0/wallapop_mcp/cli/main.py +270 -0
  31. wallapop_mcp-0.2.0/wallapop_mcp/cli/output.py +208 -0
  32. wallapop_mcp-0.2.0/wallapop_mcp/client.py +1884 -0
  33. wallapop_mcp-0.2.0/wallapop_mcp/config.py +297 -0
  34. wallapop_mcp-0.2.0/wallapop_mcp/http.py +457 -0
  35. wallapop_mcp-0.2.0/wallapop_mcp/ids.py +38 -0
  36. wallapop_mcp-0.2.0/wallapop_mcp/mcp_server.py +543 -0
  37. wallapop_mcp-0.2.0/wallapop_mcp/models.py +568 -0
  38. wallapop_mcp-0.2.0/wallapop_mcp/publish.py +221 -0
  39. wallapop_mcp-0.2.0/wallapop_mcp/py.typed +0 -0
  40. wallapop_mcp-0.2.0/wallapop_mcp/session.py +92 -0
  41. wallapop_mcp-0.2.0/wallapop_mcp/tokens.py +54 -0
  42. wallapop_mcp-0.2.0/wallapop_mcp/weblogin.py +82 -0
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.pyc
3
+ session.json
4
+ credentials.json
5
+ cookies.txt
6
+ build/
7
+ dist/
8
+ *.egg-info/
9
+ .venv/
10
+ .pytest_cache/
11
+ .ruff_cache/
12
+ .env
13
+ .env.*
14
+ .DS_Store
@@ -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).