999md-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., "@999md-mcp Find 2-room flats for rent in Chișinău under €600"
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.
999md-mcp
An MCP server for 999.md, Moldova's main classifieds board. MCP-сервер для 999.md — главной доски объявлений Молдовы.
English
Search flats, cars and phones straight from Claude, with filters, price statistics and the seller's phone number.
What it is
A read-only MCP server on top of the GraphQL API that 999.md uses for its own website
(https://999.md/graphql). No account, API key or cookies needed. The official
Partners API does not fit this job: it is paid
and only manages your own ads, with no search at all.
Tools
Tool | What it does |
🔎 | Search by text, category (id / path / 999.md link), filters, price in EUR/USD/MDL, sorting, paging |
📄 | Full ad: description, characteristics, amenities, address with coordinates, phone, seller, photo/video links |
🖼 | The ad's photos as images the model can actually see. Costly in context: ~550 tokens per compact photo (768 px, whole frame), ~1500 with |
🎛 | A subcategory's filters with feature and option ids, exactly what |
🔗 | Dependent options: cities of a region, sectors of a city, models of a brand |
🗂 | Category tree with live ad counts; with |
👤 | Seller profile (member since, verification, business plan) and their ads |
📊 | 999.md's own price statistics: median, average, min/max, sample size |
Typical flow: categories → get_filters → search → get_ad.
Example
"A two-room flat for monthly rent in Chișinău, up to €600"
{
"category": "real-estate/apartments-and-rooms",
"price_max": 600,
"currency": "EUR",
"filters": [
{"feature_id": 1, "option_ids": [912]}, // offer type: monthly rent
{"feature_id": 7, "option_ids": [12900]}, // region: Chișinău mun.
{"feature_id": 241, "option_ids": [894]} // 2 rooms
]
}999.md converts currencies server-side, so a price filter also catches ads priced in lei and dollars.
Installation
Requires uv.
git clone https://github.com/ilodezis/999md-mcp.git
cd 999md-mcp
uv syncClaude Code:
claude mcp add 999md --scope user -- uv run --directory /path/to/999md-mcp python server.pyClaude Desktop, Cursor and other clients (claude_desktop_config.json or equivalent):
{
"mcpServers": {
"999md": {
"command": "uv",
"args": ["run", "--directory", "/path/to/999md-mcp", "python", "server.py"]
}
}
}Variable | Default | What it does |
|
| Language of titles, options and descriptions: |
Remote mode (Claude.ai)
remote.py serves the same server over Streamable HTTP at /mcp, behind a single-user OAuth gate
(authorization code + PKCE S256). Claude.ai opens a consent page, the owner types the password once,
and from then on Claude calls the server with a signed Bearer token valid for a year. Nothing is stored:
authorization codes live in memory for 5 minutes, tokens are HMAC-signed. Rotating TOKEN_SECRET revokes every token.
cp .env.example .env # password, signing secret, client secret
docker compose up -d --build # listens on 127.0.0.1:8013; terminate TLS on a reverse proxyVariable | Required | What it does |
| yes | Password typed on the consent page |
| yes | Token signing key |
| yes | OAuth client secret |
| no | OAuth client id, |
| no | Comma-separated allowed callbacks, Claude.ai's by default |
In Claude.ai: Settings → Connectors → Add custom connector, URL https://<your-domain>/mcp,
then put CLIENT_ID and CLIENT_SECRET under Advanced settings.
How the site's API works
Reverse-engineered from the 999.md frontend (Next.js), not from any documentation:
POST /graphql, no authentication; schema introspection is open.The
lang: ru|roheader sets the language of translated fields.searchAds.filters: the server ignoresfilterIdand only looks atfeatureId. Features inside one group are combined with OR, groups with each other with AND, so every feature goes into its own group.An invalid category path silently turns into the root category (
id: 0); the server catches this and returns a clear error.Feature ids that are the same in every category:
1offer type,2price,7/8/9region/city/sector,13text,14photos,16contacts.
Limitations
Read-only. Posting, favourites and chat are left out on purpose.
Throttled to 5 requests per second. No hard rate limits turned up during testing.
Personal use. 999.md's terms forbid extracting, collecting or systematising its content without consent. This server is not a scraper for bulk downloads.
The API is unofficial and can change without notice. The live tests catch that right away, and CI runs them weekly.
Tests
uv run python -m pytest -q # offline + live tests against the real 999.md
OFFLINE=1 uv run python -m pytest -q # offline onlyOffline tests cover parsing and formatting; live tests check the contract with 999.md through a real MCP client.
Disclaimer
An independent project, not affiliated with or endorsed by 999.md or Simpals. All ads and their content belong to their authors and to 999.md.
Related MCP server: Turbo.az MCP Server
Русский
Поиск квартир, машин, телефонов прямо из Claude: с фильтрами, ценовой статистикой и телефоном продавца.
Что это
Read-only MCP поверх собственного GraphQL, которым 999.md кормит свой же сайт
(https://999.md/graphql): без аккаунта, API-ключа и куков. Официальный
Partners API сюда не подходит — он платный и
только для управления своими объявлениями, поиска в нём нет.
Инструменты
Tool | Что делает |
🔎 | Поиск: текст, категория (id / путь / ссылка 999.md), фильтры, цена в EUR/USD/MDL, сортировка, пагинация |
📄 | Карточка целиком: описание, характеристики, удобства, адрес с координатами, телефон, продавец, фото/видео |
🖼 | Сами фото объявления картинками, чтобы модель их видела. Дорого по контексту: ~550 токенов на сжатое фото (768 px, кадр целиком), ~1500 с |
🎛 | Фильтры подкатегории с id фич и опций — ровно то, что принимает |
🔗 | Зависимые опции: города региона, секторы города, модели марки |
🗂 | Дерево категорий со счётчиками; с |
👤 | Профиль продавца (с какого года, верификация, бизнес-план) и его объявления |
📊 | Ценовая статистика самого 999.md: медиана, среднее, min/max, размер выборки |
Типичный путь: categories → get_filters → search → get_ad.
Пример
«Двушка в аренду помесячно, Кишинёв, до 600 €»
{
"category": "real-estate/apartments-and-rooms",
"price_max": 600,
"currency": "EUR",
"filters": [
{"feature_id": 1, "option_ids": [912]}, // тип предложения: сдаю помесячно
{"feature_id": 7, "option_ids": [12900]}, // регион: Кишинёв мун.
{"feature_id": 241, "option_ids": [894]} // 2-комнатная
]
}Валюту сервер 999.md конвертирует сам, так что фильтр по цене ловит и объявления в леях и долларах.
Установка
Нужен uv.
git clone https://github.com/ilodezis/999md-mcp.git
cd 999md-mcp
uv syncClaude Code:
claude mcp add 999md --scope user -- uv run --directory /path/to/999md-mcp python server.pyClaude Desktop, Cursor и другие клиенты (claude_desktop_config.json или аналог):
{
"mcpServers": {
"999md": {
"command": "uv",
"args": ["run", "--directory", "/path/to/999md-mcp", "python", "server.py"]
}
}
}Переменная | По умолчанию | Что делает |
|
| Язык названий, опций и описаний: |
Удалённый режим (Claude.ai)
remote.py отдаёт тот же сервер по Streamable HTTP на /mcp за однопользовательским OAuth
(authorization code + PKCE S256). Claude.ai открывает страницу согласия, владелец один раз вводит пароль,
дальше Claude ходит с подписанным Bearer-токеном на год. Хранилища нет: коды авторизации живут в памяти
5 минут, токены подписаны HMAC. Смена TOKEN_SECRET отзывает все токены.
cp .env.example .env # пароль, секрет подписи, client secret
docker compose up -d --build # слушает 127.0.0.1:8013, TLS — на reverse proxyПеременная | Обязательна | Что делает |
| да | Пароль на странице согласия |
| да | Ключ подписи токенов |
| да | OAuth client secret |
| нет | OAuth client id, по умолчанию |
| нет | Разрешённые callback через запятую, по умолчанию — Claude.ai |
В Claude.ai: Settings → Connectors → Add custom connector, URL https://<домен>/mcp,
в Advanced settings — CLIENT_ID и CLIENT_SECRET.
Как устроено API сайта
Разведано по фронтенду 999.md (Next.js), не по документации:
POST /graphql, авторизация не нужна; интроспекция схемы открыта.Язык переводимых полей задаёт заголовок
lang: ru|ro.searchAds.filters: сервер игнорируетfilterId, смотрит толькоfeatureId. Фичи внутри одной группы объединяются по OR, группы между собой — по AND. Поэтому каждая фича кладётся в свою группу.Невалидный путь категории API молча превращает в корневую (
id: 0) — сервер это ловит и отдаёт понятную ошибку.Фичи с постоянными id во всех категориях:
1— тип предложения,2— цена,7/8/9— регион/город/сектор,13— текст,14— фото,16— контакты.
Ограничения
Только чтение. Постинг, избранное, чат не реализованы намеренно.
Троттлинг 5 запросов/с. Жёстких лимитов у сайта при проверке не нашлось.
Личное использование. Правила 999.md запрещают без согласия «извлекать из базы, собирать, систематизировать» контент — сервер не для массовой выгрузки.
API неофициальное и может поменяться без предупреждения. Живые тесты это сразу покажут, CI гоняет их раз в неделю.
Тесты
uv run python -m pytest -q # офлайн + живые против настоящего 999.md
OFFLINE=1 uv run python -m pytest -q # только офлайнОфлайн-тесты проверяют разбор и форматирование, живые — контракт с 999.md через настоящий MCP-клиент.
Дисклеймер
Независимый проект, не связан с 999.md и Simpals и не одобрен ими. Объявления и их содержимое принадлежат авторам и 999.md.
License / Лицензия
Available Tools
8 toolscategoriesCategoriesARead-onlyIdempotent
999.md category tree with live ad counts. No arguments: top-level categories. With category: its subcategories. With query: where ads matching the text live, biggest first.
Inputs: query, category. Returns: object
get_adGet AdARead-onlyIdempotent
Full ad: description, all characteristics, amenities, exact location with coordinates, seller's phone numbers and profile, photo and video links, dates. Photo links are text only; to actually look at the photos use the photos tool.
Inputs: ad (required). Returns: object
get_filtersGet FiltersARead-onlyIdempotent
Filters available in a subcategory, with the feature ids and option ids that search accepts. kind='options' -> pass option_ids; 'range' -> min/max (+unit); 'flag' -> feature_id alone. Features with depends_on_feature (city after region, model after brand) need get_options.
Inputs: category (required), max_options. Returns: object
get_optionsGet OptionsARead-onlyIdempotent
Options of one feature, typically a dependent one: cities of a region, sectors of a city, models of a brand. Use the returned ids in search filters.
Inputs: feature_id (required), query, parent_option_id. Returns: object
photosPhotosARead-onlyIdempotent
EXPENSIVE: returns the ad's photos as images you can see, ~550 tokens each (compact, long side 768 px) and ~1500 each with full_resolution. They stay in the conversation context for the rest of the chat. Call only when the look matters and the text of get_ad cannot answer: renovation and condition of a flat, body damage on a car, what exactly is being sold. Pick 1-3 finalists first; never call it for every ad of a search page. Page with offset instead of raising limit.
Inputs: ad (required), limit, offset, full_resolution.
price_statsPrice StatsARead-onlyIdempotent
999.md's own price estimate over matching ads: median, average, min, max and sample size. Prefer the median: min/max and the average are skewed by mistyped prices.
Inputs: category (required), options, currency. Returns: object
searchSearchARead-onlyIdempotent
Search 999.md ads by text, category and filters. Returns a page of short ad cards (price, location, date, seller login, first photo, link) plus total count and paging info.
Inputs: sort, limit, query, offset, +5 more. Returns: object
seller_adsSeller AdsBRead-onlyIdempotent
A seller's profile (registered since, verified, business plan) and their active ads. Handy to tell a private person from an agency or reseller.
Inputs: login (required), limit, query, offset. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a fairly distinct role: search finds ads, get_ad returns full detail, photos renders images, seller_ads profiles a seller, price_stats gives pricing, and categories/get_filters/get_options handle taxonomy and filter metadata. The main soft spot is the filter trio (get_filters vs get_options vs categories), though descriptions clarify their separation.
Names are readable and mostly noun/verb-noun, but conventions are mixed: get_ad, get_filters, get_options use a get_ prefix while search, photos, seller_ads, price_stats, categories do not. There is a discernible pattern but it is not applied uniformly.
Eight tools is well-scoped for a classifieds browsing server, with each tool covering a distinct and necessary capability. Nothing feels redundant or missing at the count level.
Read/browse coverage is thorough: search, full ad detail, photos, seller info, pricing stats, category tree and filter metadata. Only write operations (posting/managing ads) are absent, which is likely out of scope for this browsing-oriented server.
Related MCP Connectors
Search and browse global classifieds across 80 markets. No auth required for read-only access.
Car-listing search and used-car market analysis as agent tools.
Create, edit, relist and take down Czech and Slovak classified ads from your AI agent.
AI-agent marketplace: agent templates, web search & crawl, SEO audit, RO company data, city info.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with New Zealand's largest online marketplace through the Trade Me API. Supports searching listings, managing watchlists, placing bids, making purchases, and accessing marketplace data across all Trade Me categories.6-
- FlicenseBqualityDmaintenanceEnables users to search for vehicles and retrieve detailed listing information from the Turbo.az automotive marketplace. It supports advanced filtering by make, model, price, and other specifications through natural language queries.4-
- AlicenseAqualityCmaintenanceEnables AI assistants to search and view advertisements on Marktplaats.nl with extensive filtering options.521MIT
- AlicenseAqualityBmaintenanceEnables AI agents to search and monitor Dutch and Belgian classifieds (Marktplaats and 2dehands) for listings, seller profiles, and categories.875 PyPI5MIT