Skip to main content
Glama
deenesitjakoruzh
pindaroli

mcp-server-subito-scraper

by pindaroli
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Subito.it MCP Server (via Apify)

License: MIT Node.js Model Context Protocol

TypeScript-based MCP (Model Context Protocol) server for searching and scraping listings from Subito.it using the Apify Actor azzouzana/subito-scraper-pro-by-search-url.

Instantly executable with npx on any MCP-compatible client (Claude Desktop, Cursor, Gemini Antigravity, Windsurf, VS Code, etc.).

🌟 Key Features

  • 🚀 Run with npx, no global install: ready to use with npx -y mcp-server-subito-scraper.

  • 🇮🇹 Full support for all Subito.it categories: Motors (cars, motorcycles), Real Estate (sale/rent), Electronics/IT, Phones, Furniture, Jobs, and General Marketplace.

  • 🔍 Smart search (subito_search): Automatically generates URLs with filters for query, category, region, min/max price, and TuttoSubito shipping (shp=true).

  • 🔗 Direct URL scraping (subito_scrape_by_url): Paste any URL with complex filters applied directly from the site.

  • 📦 Dataset retrieval (subito_get_dataset_items): View and extract results from previously created Apify datasets.

  • 🔑 Flexible Token Configuration: Via environment variable (APIFY_TOKEN), command-line parameter (--token), or directly in the prompt/tool.

Related MCP server: MCP Apify

🔑 Getting an Apify Token

  1. Create a free account at Apify.com.

  2. Go to Settings > Integrations > API Tokens or console.apify.com/settings/integrations.

  3. Copy your Personal API Token (e.g. apify_api_...).

🛠️ Configuration in MCP Clients

1. Claude Desktop

Add the configuration to the claude_desktop_config.json file:

  • 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"
      }
    }
  }
}

Alternatively, passing the token as a CLI argument:

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

2. Cursor / Windsurf

In the client's MCP settings:

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

3. Gemini Antigravity / Agentic IDE

Add the MCP configuration block in the mcpServers section:

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

🧰 Available Tools

1. subito_search

Automatically builds the Subito URL and runs the scraper.

Parameter

Type

Description

Default

query

string (required)

Search text (e.g. "MacBook Pro M3", "Vespa 125")

-

category

string (optional)

Category (e.g. "usato", "auto", "moto", "case", "informatica", "telefonia", "arredamento")

"usato"

region

string (optional)

Italian region (e.g. "italia", "lombardia", "lazio", "piemonte", "veneto")

"italia"

minPrice

number (optional)

Minimum price in Euros

-

maxPrice

number (optional)

Maximum price in Euros

-

shippingOnly

boolean (optional)

Filter only listings with TuttoSubito shipping

false

sortBy

string (optional)

Sorting: "datedesc", "priceasc", "pricedesc"

"datedesc"

maxItems

number (optional)

Maximum number of listings to extract

30

timeoutSecs

number (optional)

Maximum execution timeout in seconds

300

token

string (optional)

Apify token (overrides the environment one)

-

2. subito_scrape_by_url

Scrapes from a ready-made direct search URL.

Parameter

Type

Description

Default

searchUrl

string (required)

Full Subito.it search URL

-

maxItems

number (optional)

Maximum number of listings to extract

30

timeoutSecs

number (optional)

Timeout in seconds

300

token

string (optional)

Custom Apify token

-

3. subito_get_dataset_items

Retrieves extracted data from a previously saved Apify dataset.

Parameter

Type

Description

Default

datasetId

string (required)

Apify dataset ID

-

limit

number (optional)

Number of items to read

50

offset

number (optional)

Offset for pagination

0

token

string (optional)

Apify token

-

4. apify_check_status

Checks that the Apify token is valid and displays account information.

💻 Local Development and Compilation

If you want to clone and modify the server locally:

# 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

Or in development mode with hot reload:

APIFY_TOKEN=tuo_token_qui npm run dev

🚀 Publishing to NPM and GitHub

To publish the package and make it available to everyone via npx mcp-server-subito-scraper:

# Esegui il login a npm
npm login

# Pubblica il pacchetto
npm publish --access public

📄 License

This project is distributed under the MIT license. See the LICENSE file for details.

Disclaimer: This MCP server is not officially affiliated with, sponsored, or endorsed by Subito.it S.r.l. All trademarks belong to their respective owners.

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

  • Reddit MCP Server

    mypracticaltools
    A
    license
    B
    quality
    D
    maintenance
    Enables AI agents to search Reddit for posts, comments, and users or monitor for high-intent leads and brand mentions. It functions by delegating scraping tasks to high-performance Apify cloud actors.
    2
    27 npm
    7
    MIT

  • MCP Apify

    fvegah
    A
    license
    B
    quality
    F
    maintenance
    Enables AI assistants to interact with the Apify platform to manage actors, monitor runs, and retrieve scraped data from datasets. It supports natural language commands for executing web scrapers, managing tasks, and accessing key-value stores.
    28
    MIT