Skip to main content
Glama
deenesitjakoruzh
pindaroli

mcp-server-subito-scraper

by pindaroli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Subito.it MCP Server (через Apify)

Лицензия: MIT Node.js Model Context Protocol

MCP (Model Context Protocol) сервер на TypeScript для поиска и парсинга объявлений с Subito.it с использованием Apify Actor azzouzana/subito-scraper-pro-by-search-url.

Запускается мгновенно с помощью npx на любом клиенте, совместимом с MCP (Claude Desktop, Cursor, Gemini Antigravity, Windsurf, VS Code и др.).

🌟 Основные возможности

  • 🚀 Запуск через npx без глобальной установки: готов к использованию с npx -y mcp-server-subito-scraper.

  • 🇮🇹 Полная поддержка всех категорий Subito.it: Авто (автомобили, мотоциклы), Недвижимость (продажа/аренда), Электроника/IT, Телефония, Мебель, Работа и общий Marketplace.

  • 🔍 Умный поиск (subito_search): Автоматически генерирует URL с фильтрами по запросу, категории, региону, минимальной/максимальной цене и доставке TuttoSubito (shp=true).

  • 🔗 Парсинг по прямому URL (subito_scrape_by_url): Вставьте любой URL с применёнными на сайте сложными фильтрами.

  • 📦 Получение датасета (subito_get_dataset_items): Просматривайте и извлекайте результаты из ранее созданных датасетов Apify.

  • 🔑 Гибкая настройка токена: Через переменную окружения (APIFY_TOKEN), параметр командной строки (--token), или непосредственно в запросе/инструменте.

Related MCP server: OLX MCP Server

🔑 Получение токена Apify

  1. Создайте бесплатную учётную запись на Apify.com.

  2. Перейдите в Settings > Integrations > API Tokens или на console.apify.com/settings/integrations.

  3. Скопируйте ваш Personal API Token (например, apify_api_...).

🛠️ Настройка в клиентах MCP

1. Claude Desktop

Добавьте конфигурацию в файл claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "subito-scraper": {
      "command": "npx",
      "args": ["-y", "mcp-server-subito-scraper"],
      "env": {
        "APIFY_TOKEN": "IL_TUO_TOKEN_APIFY_QUI"
      }
    }
  }
}

В качестве альтернативы, передав токен как аргумент CLI:

{
  "mcpServers": {
    "subito-scraper": {
      "command": "npx",
      "args": ["-y", "mcp-server-subito-scraper", "--token", "IL_TUO_TOKEN_APIFY_QUI"]
    }
  }
}

2. Cursor / Windsurf

В настройках MCP клиента:

{
  "subito-scraper": {
    "command": "npx",
    "args": ["-y", "mcp-server-subito-scraper"],
    "env": {
      "APIFY_TOKEN": "IL_TUO_TOKEN_APIFY_QUI"
    }
  }
}

3. Gemini Antigravity / Agentic IDE

Добавьте блок конфигурации MCP в секцию mcpServers:

{
  "mcpServers": {
    "subito-scraper": {
      "command": "npx",
      "args": ["-y", "mcp-server-subito-scraper"],
      "env": {
        "APIFY_TOKEN": "IL_TUO_TOKEN_APIFY_QUI"
      }
    }
  }
}

🧰 Доступные инструменты

1. subito_search

Автоматически формирует URL Subito и запускает парсер.

Параметр

Тип

Описание

По умолчанию

query

string (обязательный)

Текст для поиска (например, "MacBook Pro M3", "Vespa 125")

-

category

string (опциональный)

Категория (например, "usato", "auto", "moto", "case", "informatica", "telefonia", "arredamento")

"usato"

region

string (опциональный)

Регион Италии (например, "italia", "lombardia", "lazio", "piemonte", "veneto")

"italia"

minPrice

number (опциональный)

Минимальная цена в евро

-

maxPrice

number (опциональный)

Максимальная цена в евро

-

shippingOnly

boolean (опциональный)

Фильтр только объявлений с доставкой TuttoSubito

false

sortBy

string (опциональный)

Сортировка: "datedesc", "priceasc", "pricedesc"

"datedesc"

maxItems

number (опциональный)

Максимальное количество объявлений для извлечения

30

timeoutSecs

number (опциональный)

Максимальное время выполнения в секундах

300

token

string (опциональный)

Токен Apify (переопределяет переменную окружения)

-

2. subito_scrape_by_url

Выполняет парсинг по уже готовому прямому URL поиска.

Параметр

Тип

Описание

По умолчанию

searchUrl

string (обязательный)

Полный URL поиска Subito.it

-

maxItems

number (опциональный)

Максимальное количество объявлений

30

timeoutSecs

number (опциональный)

Тайм-аут в секундах

300

token

string (опциональный)

Пользовательский токен Apify

-

3. subito_get_dataset_items

Извлекает данные из ранее сохранённого датасета Apify.

Параметр

Тип

Описание

По умолчанию

datasetId

string (обязательный)

ID датасета Apify

-

limit

number (опциональный)

Количество элементов для чтения

50

offset

number (опциональный)

Смещение для пагинации

0

token

string (опциональный)

Токен Apify

-

4. apify_check_status

Проверяет, действителен ли токен Apify, и показывает информацию об аккаунте.

💻 Локальная разработка и сборка

Если вы хотите клонировать и изменить сервер локально:

# 1. Clona il repository
git clone https://github.com/pindaroli/mcp-server-subito-scraper.git
cd mcp-server-subito-scraper

# 2. Installa le dipendenze
npm install

# 3. Compila il codice TypeScript
npm run build

# 4. Esegui in modalità test
APIFY_TOKEN=tuo_token_qui npm start

Или в режиме разработки с быстрой перезагрузкой:

APIFY_TOKEN=tuo_token_qui npm run dev

🚀 Публикация на NPM и GitHub

Чтобы опубликовать пакет и сделать его доступным для всех через npx mcp-server-subito-scraper:

# Esegui il login a npm
npm login

# Pubblica il pacchetto
npm publish --access public

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

Отказ от ответственности: Данный сервер MCP не связан, не спонсируется и не поддерживается официально Subito.it S.r.l. Товарные знаки принадлежат их владельцам.

Available Tools

4 tools
apify_check_statusB

Checks the status of the Apify account and validates the API token

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenNoOptional Apify API Token to test

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions checking status and validating a token, but does not state whether the tool is read-only, what it returns, or any side effects. For a tool with no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded and free of extraneous words. It conveys the core purpose efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain what the agent can expect as a response (e.g., success/failure, account details). It does not, leaving a significant gap in understanding the tool's behavior. Given the simplicity of the tool (1 optional param), a more complete description is expected.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'token' with a basic description. The description adds value by explaining that the tool validates the token, which goes beyond the schema's 'Optional Apify API Token to test' – it implies the token is tested for validity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Checks the status of the Apify account and validates the API token.' It uses specific verbs ('checks', 'validates') and a specific resource ('Apify account', 'API token'), distinguishing it from sibling tools that deal with scraping and searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no context about when a status check is appropriate. It is purely a statement of function without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

subito_get_dataset_itemsC

Fetches scraped items from a previously generated Apify dataset ID

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoLimit number of items to fetch
tokenNoOptional Apify API Token
offsetNoOffset for pagination
datasetIdYesThe Apify Dataset ID to fetch items from

TDQS

C2.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description adds no behavioral context. It fails to disclose any notable traits such as authentication requirements (token is optional), rate limits, pagination behavior, error handling, or what happens if the datasetId is invalid. The agent has no insight into side effects or restrictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but overly minimal. It is front-loaded with the key action, but it lacks any structure or additional information. Every sentence should earn its place, and this one is too sparse to be considered efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should cover return values, prerequisites, and pagination behavior. It does not mention that the dataset must already exist from a previous scrape, nor does it describe the format of the returned items. This is insufficient for a tool with four parameters and pagination.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already describes all four parameters. The description adds no additional meaning beyond the schema. While it does not repeat the schema, it also does not explain how parameters like offset and limit relate for pagination, which would be helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('fetches scraped items') and the resource ('from a previously generated Apify dataset ID'). It distinguishes this tool from siblings like subito_scrape_by_url (scraping) and subito_search (searching) by focusing on existing datasets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It does not mention that it should be used after scraping, nor does it explain when to use subito_search or apify_check_status instead. No exclusions or prerequisites are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

subito_scrape_by_urlB

Scrapes classified ads directly from a Subito.it search URL using Apify Actor (azzouzana/subito-scraper-pro-by-search-url)

ParametersJSON Schema
NameRequiredDescriptionDefault
tokenNoOptional Apify API Token (overrides APIFY_TOKEN environment variable)
maxItemsNoMaximum number of ads/listings to retrieve (default: 30)
searchUrlYesFull Subito.it search URL to scrape (e.g. "https://www.subito.it/annunci-italia/vendita/usato/?q=iphone+15")
timeoutSecsNoTimeout in seconds for Apify Actor execution (default: 300)

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It mentions the use of an Apify Actor and provides parameters like timeout, which hints at asynchronous behavior. However, it does not disclose whether the tool is synchronous or asynchronous, if it returns results directly or only initiates a run, or what happens on failure (e.g., invalid URL, Actor timeout). The description is adequate but leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that conveys the core purpose and implementation. It wastes no words and is easy to parse. This is exemplary conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, 4 parameters, and no annotations, the description is too brief. It does not explain the return format (e.g., what the scraped data looks like), error behavior, or how to handle the Apify Actor lifecycle (e.g., need to check status or get dataset items separately). The presence of sibling tools like 'apify_check_status' and 'subito_get_dataset_items' suggests a pipeline, but the description does not connect them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (all 4 parameters have descriptions). The tool description adds no additional parameter details, but the schema itself is complete and clear. The baseline is 3 per the rubric; the description includes the full search URL format example, which adds marginal value. Thus a score of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('scrapes classified ads'), the specific source ('directly from a Subito.it search URL'), and the implementation ('using Apify Actor'). The name 'subito_scrape_by_url' reinforces this. While the purpose is clear, it does not explicitly distinguish from siblings like 'subito_search' which might serve a similar but different purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'subito_search' or 'subito_get_dataset_items'. It does not mention prerequisites (e.g., valid search URL format), when not to use it, or what to do after scraping (e.g., check status or retrieve items). The agent is left to infer usage from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.0.0
    • First observedapify_check_status
    • First observedsubito_get_dataset_items
    • First observedsubito_scrape_by_url
    • First observedsubito_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 4 tools

Disambiguation4/5

Each tool targets a distinct aspect: scraping by URL vs. by search parameters, checking account status, and retrieving dataset items. There is slight potential confusion between subito_scrape_by_url and subito_search, but their descriptions clarify the difference (URL vs. keyword-based).

Naming Consistency4/5

Tool names use a consistent verb_noun pattern with a domain prefix (subito_). Names are descriptive and follow a predictable structure, though subito_search could optionally be subito_search_by_keywords for perfect parallelism with subito_scrape_by_url.

Tool Count5/5

Four tools are appropriate for a focused scraping server: two scraping methods, one status check, and one data retrieval tool. Each tool has a clear purpose and no unnecessary bloat.

Completeness3/5

The tool surface covers scraping, search, status checking, and data retrieval, but lacks ability to list or manage datasets (e.g., delete old datasets). An agent scraping multiple times may accumulate datasets without cleanup, which is a notable gap.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers