listam-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@listam-mcp Find 2-room apartments for rent in Arabkir under $700"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
listam-mcp
An MCP server for list.am, Armenia's largest classifieds site. It lets Claude (or any MCP client) search listings in every category, read full ad details and track saved searches for new ads.
Unofficial project, not affiliated with list.am. list.am has no public API, so this server reads the public website. Use it for personal, low-volume purposes and respect list.am's Terms of Service.
What you can ask
"Find 2-room apartments for rent in Arabkir under $700 a month, owners only, and compare the best five."
"Search for a used iPhone 15 under 350,000 AMD and tell me which ads look like the best deal."
"Save this search as
kentron-rentand tell me tomorrow what's new.""Open ad 24201365 and summarize the pros and cons."
Related MCP server: 999md-mcp
Tools
Tool | Description |
| Search any category by text, category, region and price (AMD/USD/EUR/RUB), optionally excluding agencies. Returns compact rows by default; pass |
| Run a search URL copied from the browser, keeping every filter list.am supports. |
| A category's own filters (condition, rooms, mileage, transmission...) and their values, for |
| Full details of an ad: price, attributes, description, seller, images, posted/renewed dates. |
| Full details of several ads in one call (fetched one at a time, throttled) — for checking a handful of candidates at once. |
| Discover category IDs (top level, or the subcategories of a category). |
| Save a search and later get only the listings that are new since the last check. |
| Manage saved searches (stored in SQLite). |
Tip: get_filters(category_id) returns each category's own filters (rooms, floor, mileage, renovation...) and the param/value to pass in search_listings' extra_params. A multi: true filter accepts more than one value on list.am, but extra_params can only set one value per key — for more than one, apply the filter on list.am in a browser and use search_by_url or save_search with the resulting URL.
Installation
Requires Python 3.10+. The easiest way is uv, which runs the server straight from GitHub:
uvx --from git+https://github.com/<your-username>/listam-mcp listam-mcp --helpOr install it locally:
git clone https://github.com/<your-username>/listam-mcp
cd listam-mcp
pip install -e .Claude Desktop
Add this to claude_desktop_config.json (Settings → Developer → Edit Config) and restart Claude:
{
"mcpServers": {
"listam": {
"command": "uvx",
"args": ["--from", "git+https://github.com/<your-username>/listam-mcp", "listam-mcp"]
}
}
}Claude Code
claude mcp add listam -- uvx --from git+https://github.com/<your-username>/listam-mcp listam-mcpRemote (HTTP) mode
listam-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# MCP endpoint: http://127.0.0.1:8000/mcpConfiguration
All settings are optional environment variables:
Variable | Default | Meaning |
|
| Site language: |
|
| Minimum seconds between requests to list.am. |
|
| Seconds to cache fetched pages. |
|
| HTTP timeout in seconds. |
|
| Retries (with growing backoff) after a 403/429 before giving up. |
|
| Approximate AMD per currency unit, used for cross-currency price filters. |
|
| Where the saved-search database lives. |
| browser-like UA | User-Agent header. |
Development
pip install -e ".[dev]"
pytest
ruff check .
# Debug commands hit the live site and print JSON — handy when list.am changes its HTML:
listam-mcp search "iphone 15"
listam-mcp search --category 56
listam-mcp get 24201365
listam-mcp categoriesYou can also explore the tools interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector listam-mcpHow it works
src/listam_mcp/
├── server.py # MCP tools + CLI entry point
├── client.py # async HTTP client: rate limiting, caching, list.am-only URL guard
├── parsing.py # HTML → data models (the only place that knows the page layout)
├── storage.py # SQLite for saved searches and seen listing IDs
├── models.py # dataclasses returned by tools
└── config.py # environment-based settingsThe parser relies on stable signals (/item/<id> and /category/<id> links, <h1>, og: meta tags and visible text) rather than CSS class names. Each listing also carries its raw card text and attribute lines, so the model can still read the data if a heuristic misses a field. When list.am changes its layout, update parsing.py, refresh the fixtures in tests/fixtures/ and run the tests.
Responsible use
Requests are serialized and throttled, and results are cached.
Only
list.amURLs can be fetched, so the tools can't be used to reach other hosts.Don't use it for bulk data collection, reselling data or contacting sellers at scale.
License
Available Tools
10 toolscheck_saved_searchA
Return listings that appeared since the last check of a saved search.
The first check records a baseline and returns everything currently listed.
Inputs: name (required), max_pages. Returns: object
delete_saved_searchBDestructive
Delete a saved search and its seen-listing history.
Inputs: name (required). Returns: object
get_filtersARead-only
List a category's own filters (condition, rooms, mileage, transmission...) and their values.
Each filter's param is a key to set in search_listings' extra_params (or in a
URL for search_by_url/save_search). A "select" filter takes one of options'
values. A "range" filter instead has a param/to_param pair for the from/to
bounds (e.g. floor-from, floor-to) and no options. A multi: true filter accepts
more than one value on list.am, but extra_params can only set one value per key;
for more than one, apply the filter on list.am in a browser and use search_by_url.
Inputs: category_id (required). Returns: object
get_listingARead-only
Get full details of one listing: price, attributes, description, seller, images, dates.
Inputs: item (required). Returns: object
get_listingsARead-only
Get full details of several listings in one call (fetched one at a time, throttled).
Use this to check a handful of candidates from a search instead of calling get_listing repeatedly.
Inputs: items (required). Returns: object
list_categoriesARead-only
List list.am categories (ID and name). Pass a category_id to see its subcategories.
Inputs: category_id. Returns: object
list_saved_searchesBRead-only
List saved searches with their last check time.
Inputs: no named parameters. Returns: result
save_searchC
Save a search so check_saved_search can report only new listings later.
Inputs: name (required), url, query, region_id, +1 more. Returns: object
search_by_urlARead-only
Fetch results for an existing list.am search URL, keeping all its filters.
Inputs: url (required), full, limit, max_pages. Returns: object
search_listingsARead-only
Search list.am listings in any category.
Price filters are applied locally to the fetched pages using approximate exchange rates, so fetch more pages when filtering heavily.
Inputs: full, page, limit, query, +8 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Tools are largely distinct by resource+action. The main potential confusion is between get_listing and get_listings, and between search_listings and search_by_url, but descriptions explicitly clarify when to use each (bulk vs single, native filters vs existing URL).
All tools use a consistent snake_case verb_noun pattern (get_listing, list_categories, save_search, delete_saved_search, etc.). Singular/plural variants are intentional and clear.
Ten tools is well-scoped for a listing-site client: search, detail retrieval, metadata helpers, and saved-search lifecycle. Each tool maps to a distinct user workflow without excess.
The surface covers search (two modes), listing details (single and bulk), categories, filters, and saved-search CRUD. Minor gap: no direct way to update an existing saved search's parameters (must delete and recreate), but core read workflows are complete.
Maintenance
Related MCP Connectors
Search and browse global classifieds across 80 markets. No auth required for read-only access.
Read-only search of Québec's bilingual classifieds: ads, categories, filters, places.
Every ad of any advertiser, as one MCP tool through Apify
A jobs data API and MCP server. Every listing comes from the employer's own career site, an ATS feed or a government employment service, never resold from another board. Each row names its source and when we last confirmed the vacancy existed, and a role that disappears keeps a closure date and a reason. Six tools: search_jobs, get_job, company_hiring, market_signals, coverage, changes_since.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables searching and browsing ss.ge real estate listings with filters, counters, full card details, and geo/city data via MCP tools.616 npmMIT
- AlicenseAqualityCmaintenanceEnables searching Moldova's largest classifieds board from an AI client without an account or API key, covering listings such as apartments, cars and phones with category, filter, price and currency controls. Also retrieves full ad details, photos as visible images, seller profiles and phone numbers, dependent options like city sectors or car models, and 999.md's own price statistics.8MIT
- AlicenseAqualityBmaintenanceEnables MCP-capable agents to search live Iranian classifieds on Divar, read full posts, and analyze market prices against current listings.82MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents and humans to search and browse listings on Slovenia's largest classifieds marketplace, filter by price, region, and category, and retrieve listing details and seller profiles through MCP tools.MIT