scrapemapsapi-mcp 0.1.0__py3-none-any.whl

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.
@@ -0,0 +1,3 @@
1
+ """ScrapeMapsAPI MCP server: Google Maps places and reviews tools for AI assistants."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,167 @@
1
+ """Async HTTP client for the ScrapeMapsAPI REST API (kept dependency-free on purpose)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ from dataclasses import dataclass
7
+ from typing import Any, Optional
8
+ from urllib.parse import quote
9
+
10
+ import httpx
11
+
12
+ from . import __version__
13
+ from .errors import ConnectionFailedError, ScrapeMapsAPIError, error_from_response
14
+
15
+ DEFAULT_BASE_URL = "https://api.scrapemapsapi.com"
16
+ DEFAULT_TIMEOUT = 60.0
17
+ RETRY_STATUSES = frozenset({429, 502, 503})
18
+ NO_RETRY_CODES = frozenset({"insufficient_credits_retry_later"})
19
+
20
+
21
+ @dataclass
22
+ class ApiResult:
23
+ """Parsed JSON body plus the billing headers."""
24
+
25
+ body: dict[str, Any]
26
+ credits_used: Optional[int] = None
27
+ credits_remaining: Optional[int] = None
28
+
29
+ @property
30
+ def data(self) -> Any:
31
+ return self.body.get("data")
32
+
33
+ @property
34
+ def pagination(self) -> dict[str, Any]:
35
+ return self.body.get("pagination") or {}
36
+
37
+ @property
38
+ def meta(self) -> dict[str, Any]:
39
+ return self.body.get("meta") or {}
40
+
41
+
42
+ def _int(value: Optional[str]) -> Optional[int]:
43
+ try:
44
+ return int(value) if value is not None else None
45
+ except ValueError:
46
+ return None
47
+
48
+
49
+ def place_path(place: str, suffix: str = "") -> str:
50
+ return f"/v1/places/{quote(place.strip(), safe='')}{suffix}"
51
+
52
+
53
+ class ScrapeMapsAPIClient:
54
+ """Async wrapper around the ScrapeMapsAPI REST API, with a short retry on 429/502/503."""
55
+
56
+ def __init__(
57
+ self,
58
+ api_key: str,
59
+ base_url: str = DEFAULT_BASE_URL,
60
+ max_retries: int = 1,
61
+ retry_wait: float = 1.0,
62
+ max_retry_wait: float = 10.0,
63
+ transport: Optional[httpx.AsyncBaseTransport] = None,
64
+ ) -> None:
65
+ self.base_url = base_url.rstrip("/")
66
+ self.max_retries = max_retries
67
+ self.retry_wait = retry_wait
68
+ self.max_retry_wait = max_retry_wait
69
+ self._client = httpx.AsyncClient(
70
+ base_url=self.base_url,
71
+ headers={
72
+ "X-API-Key": api_key,
73
+ "Accept": "application/json",
74
+ "User-Agent": f"scrapemapsapi-mcp/{__version__}",
75
+ },
76
+ timeout=DEFAULT_TIMEOUT,
77
+ transport=transport,
78
+ )
79
+
80
+ async def _get(self, path: str, params: dict[str, Any]) -> ApiResult:
81
+ params = {k: v for k, v in params.items() if v is not None}
82
+ attempt = 0
83
+ while True:
84
+ try:
85
+ response = await self._client.get(path, params=params)
86
+ except httpx.TransportError as e:
87
+ if attempt >= self.max_retries:
88
+ raise ConnectionFailedError(f"Could not reach {self.base_url}: {e}") from e
89
+ wait = self.retry_wait
90
+ else:
91
+ if response.is_success:
92
+ try:
93
+ body = response.json()
94
+ except ValueError as e:
95
+ raise ScrapeMapsAPIError("The API returned invalid JSON", response.status_code) from e
96
+ return ApiResult(
97
+ body=body if isinstance(body, dict) else {"data": body},
98
+ credits_used=_int(response.headers.get("x-credits-used")),
99
+ credits_remaining=_int(response.headers.get("x-credits-remaining")),
100
+ )
101
+ error = error_from_response(response)
102
+ if (
103
+ attempt >= self.max_retries
104
+ or response.status_code not in RETRY_STATUSES
105
+ or error.code in NO_RETRY_CODES
106
+ or (error.retry_after or 0) > self.max_retry_wait
107
+ ):
108
+ raise error
109
+ wait = error.retry_after if error.retry_after is not None else self.retry_wait
110
+ attempt += 1
111
+ await asyncio.sleep(wait)
112
+
113
+ async def search(
114
+ self,
115
+ query: str,
116
+ *,
117
+ language: Optional[str] = None,
118
+ region: Optional[str] = None,
119
+ lat: Optional[float] = None,
120
+ lng: Optional[float] = None,
121
+ radius_km: Optional[float] = None,
122
+ limit: Optional[int] = None,
123
+ cursor: Optional[str] = None,
124
+ ) -> ApiResult:
125
+ return await self._get(
126
+ "/v1/places/search",
127
+ {
128
+ "q": query,
129
+ "language": language,
130
+ "region": region,
131
+ "lat": lat,
132
+ "lng": lng,
133
+ "radius_km": radius_km,
134
+ "limit": limit,
135
+ "cursor": cursor,
136
+ },
137
+ )
138
+
139
+ async def get_place(self, place: str, *, language: Optional[str] = None, region: Optional[str] = None) -> ApiResult:
140
+ return await self._get(place_path(place), {"language": language, "region": region})
141
+
142
+ async def get_reviews(
143
+ self,
144
+ place: str,
145
+ *,
146
+ sort: Optional[str] = None,
147
+ language: Optional[str] = None,
148
+ original_language: Optional[str] = None,
149
+ limit: Optional[int] = None,
150
+ cursor: Optional[str] = None,
151
+ ) -> ApiResult:
152
+ return await self._get(
153
+ place_path(place, "/reviews"),
154
+ {
155
+ "sort": sort,
156
+ "language": language,
157
+ "original_language": original_language,
158
+ "limit": limit,
159
+ "cursor": cursor,
160
+ },
161
+ )
162
+
163
+ async def resolve(self, input: str) -> ApiResult:
164
+ return await self._get("/v1/places/resolve", {"input": input})
165
+
166
+ async def close(self) -> None:
167
+ await self._client.aclose()
@@ -0,0 +1,148 @@
1
+ """Typed errors for the ScrapeMapsAPI API, with messages written for an AI assistant."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Optional
6
+
7
+ import httpx
8
+
9
+ BILLING_URL = "https://scrapemapsapi.com/dashboard/billing"
10
+ API_KEYS_URL = "https://scrapemapsapi.com/dashboard/api-keys"
11
+
12
+
13
+ class ScrapeMapsAPIError(Exception):
14
+ """Base error for the ScrapeMapsAPI API."""
15
+
16
+ hint: str = ""
17
+
18
+ def __init__(
19
+ self,
20
+ message: str,
21
+ status_code: Optional[int] = None,
22
+ code: Optional[str] = None,
23
+ retry_after: Optional[float] = None,
24
+ ) -> None:
25
+ self.message = message
26
+ self.status_code = status_code
27
+ self.code = code
28
+ self.retry_after = retry_after
29
+ super().__init__(message)
30
+
31
+ def for_tool(self) -> str:
32
+ """Readable message for a tool error: what happened and what to do next."""
33
+ parts = [self.message.rstrip(".") + "."]
34
+ if self.code:
35
+ parts.append(f"(error: {self.code})")
36
+ if self.hint:
37
+ parts.append(self.hint)
38
+ if self.retry_after:
39
+ parts.append(f"Retry after {int(self.retry_after)} seconds.")
40
+ return " ".join(parts)
41
+
42
+
43
+ class InvalidRequestError(ScrapeMapsAPIError):
44
+ hint = (
45
+ "Pass a place ID (ChIJ...), a CID (digits) or a feature ID (0x...:0x...); "
46
+ "for a Google Maps URL use resolve_place first."
47
+ )
48
+
49
+
50
+ class AuthenticationError(ScrapeMapsAPIError):
51
+ hint = f"Check the SCRAPEMAPSAPI_API_KEY environment variable of the MCP server ({API_KEYS_URL})."
52
+
53
+
54
+ class InsufficientCreditsError(ScrapeMapsAPIError):
55
+ hint = f"The account is out of credits: the user can top up at {BILLING_URL}."
56
+
57
+
58
+ class NotFoundError(ScrapeMapsAPIError):
59
+ hint = "Check the identifier, or find the place with search_places."
60
+
61
+
62
+ class RateLimitError(ScrapeMapsAPIError):
63
+ hint = "Too many requests: wait before calling again."
64
+
65
+
66
+ class UpstreamError(ScrapeMapsAPIError):
67
+ hint = "Temporary problem with Google Maps; nothing was charged. Try again in a minute."
68
+
69
+
70
+ class ServiceUnavailableError(UpstreamError):
71
+ pass
72
+
73
+
74
+ class ConnectionFailedError(ScrapeMapsAPIError):
75
+ hint = "The ScrapeMapsAPI API could not be reached. Check the network or SCRAPEMAPSAPI_BASE_URL."
76
+
77
+
78
+ _CODE_MAP: dict[str, type[ScrapeMapsAPIError]] = {
79
+ "invalid_place_id": InvalidRequestError,
80
+ "invalid_cursor": InvalidRequestError,
81
+ "invalid_location": InvalidRequestError,
82
+ "validation_error": InvalidRequestError,
83
+ "missing_api_key": AuthenticationError,
84
+ "invalid_api_key": AuthenticationError,
85
+ "insufficient_credits": InsufficientCreditsError,
86
+ "insufficient_credits_retry_later": InsufficientCreditsError,
87
+ "place_not_found": NotFoundError,
88
+ "rate_limited": RateLimitError,
89
+ "rate_limit_exceeded": RateLimitError,
90
+ "upstream_error": UpstreamError,
91
+ "upstream_unavailable": ServiceUnavailableError,
92
+ }
93
+
94
+ _STATUS_MAP: dict[int, type[ScrapeMapsAPIError]] = {
95
+ 400: InvalidRequestError,
96
+ 401: AuthenticationError,
97
+ 402: InsufficientCreditsError,
98
+ 404: NotFoundError,
99
+ 422: InvalidRequestError,
100
+ 429: RateLimitError,
101
+ 502: UpstreamError,
102
+ 503: ServiceUnavailableError,
103
+ }
104
+
105
+
106
+ def _parse(status: int, body: Any, text: str) -> tuple[Optional[str], str]:
107
+ code: Optional[str] = None
108
+ message = text.strip()[:300] or f"HTTP {status}"
109
+ if isinstance(body, dict):
110
+ detail = body.get("detail", body)
111
+ if isinstance(detail, dict):
112
+ code = detail.get("error") if isinstance(detail.get("error"), str) else None
113
+ if isinstance(detail.get("message"), str):
114
+ message = detail["message"]
115
+ elif isinstance(detail, list): # FastAPI 422
116
+ code = "validation_error"
117
+ msgs = []
118
+ for item in detail:
119
+ if isinstance(item, dict):
120
+ loc = ".".join(str(p) for p in item.get("loc", []) if p not in ("query", "path"))
121
+ msgs.append(f"{loc}: {item.get('msg', 'invalid value')}" if loc else str(item.get("msg")))
122
+ if msgs:
123
+ message = "Invalid parameters: " + "; ".join(msgs)
124
+ elif isinstance(detail, str):
125
+ message = detail
126
+ return code, message
127
+
128
+
129
+ def error_from_response(response: httpx.Response) -> ScrapeMapsAPIError:
130
+ try:
131
+ body: Any = response.json()
132
+ except Exception:
133
+ body = None
134
+ code, message = _parse(response.status_code, body, response.text if body is None else "")
135
+ # 5xx: the status decides (an upstream code such as "rate_limited" is not a client rate limit).
136
+ by_code = _CODE_MAP.get(code or "") if response.status_code < 500 else None
137
+ cls = by_code or _STATUS_MAP.get(response.status_code, ScrapeMapsAPIError)
138
+ retry_after: Optional[float] = None
139
+ try:
140
+ retry_after = float(response.headers.get("retry-after", ""))
141
+ except ValueError:
142
+ pass
143
+ return cls(message, status_code=response.status_code, code=code, retry_after=retry_after)
144
+
145
+
146
+ def raise_for_status(response: httpx.Response) -> None:
147
+ if not response.is_success:
148
+ raise error_from_response(response)
@@ -0,0 +1,79 @@
1
+ """MCP prompt templates for common places and reviews workflows."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Optional
6
+
7
+ from mcp.server.fastmcp import FastMCP
8
+
9
+
10
+ def register_prompts(mcp: FastMCP) -> None:
11
+ """Register prompt templates on the MCP server."""
12
+
13
+ @mcp.prompt()
14
+ async def summarize_reviews(place: str, language: str = "en", max_reviews: int = 100) -> str:
15
+ """Summarize what customers say about a place, from its reviews.
16
+
17
+ Args:
18
+ place: Place name with its city, a Google Maps URL, a place ID (ChIJ...), CID or feature ID.
19
+ language: Language for the reviews and the summary, e.g. 'en', 'it'.
20
+ max_reviews: How many reviews to read at most (cost: 1 credit per page of 20 reviews).
21
+ """
22
+ return (
23
+ f"Summarize the Google Maps reviews of: {place}\n\n"
24
+ "Steps:\n"
25
+ "1. Identify the place: if it is a URL, call `resolve_place`; if it is a name, call "
26
+ "`search_places` and pick the matching result (ask me if several match); if it is an ID, use it.\n"
27
+ "2. Call `get_place` for the name, rating and review count.\n"
28
+ f'3. Call `get_reviews` with sort="newest", language="{language}", limit=20, following the '
29
+ f"cursor until you have read about {max_reviews} reviews or there are no more.\n"
30
+ '4. If the newest reviews are few or one-sided, also read one page with sort="lowest".\n'
31
+ f"5. Write the summary in {language}:\n"
32
+ " - **Overall verdict** (2-3 sentences, with the rating and how many reviews you read)\n"
33
+ " - **What people love** (bullets, with how often it comes up)\n"
34
+ " - **Common complaints** (bullets, with how often it comes up)\n"
35
+ " - **Recent trend** (are the latest reviews better or worse than the average?)\n"
36
+ " - **Owner replies** (does the owner answer, and how?)\n"
37
+ "Quote short excerpts as evidence. Do not invent reviews.\n"
38
+ )
39
+
40
+ @mcp.prompt()
41
+ async def compare_places(places: str, criteria: Optional[str] = None) -> str:
42
+ """Compare several places side by side using details and reviews.
43
+
44
+ Args:
45
+ places: Places separated by ';' (names with city, URLs or IDs), e.g. 'Da Michele, Naples; Sorbillo, Naples'.
46
+ criteria: What matters most, e.g. 'price, waiting time, gluten-free options'.
47
+ """
48
+ items = [p.strip() for p in places.split(";") if p.strip()]
49
+ listed = "\n".join(f"- {p}" for p in items)
50
+ focus = f" Focus on: {criteria}." if criteria else ""
51
+ return (
52
+ f"Compare these places:\n{listed}\n\n"
53
+ "Steps:\n"
54
+ "1. Find each place (`resolve_place` for URLs, `search_places` for names) and call `get_place`.\n"
55
+ '2. For each place read two pages of reviews with `get_reviews` (sort="newest", then the cursor).\n'
56
+ "3. Produce a comparison table (rating, review count, price level if mentioned, hours, "
57
+ "strengths, weaknesses), then a short recommendation for different kinds of visitors."
58
+ f"{focus}\n"
59
+ )
60
+
61
+ @mcp.prompt()
62
+ async def find_best_places(what: str, where: str, how_many: int = 5) -> str:
63
+ """Find and rank the best places of a kind in an area, checking recent reviews.
64
+
65
+ Args:
66
+ what: What to look for, e.g. 'ramen', 'coworking', 'vet open on Sunday'.
67
+ where: City or neighbourhood.
68
+ how_many: How many places to recommend.
69
+ """
70
+ return (
71
+ f'Find the {how_many} best options for "{what}" in {where}.\n\n'
72
+ "Steps:\n"
73
+ f'1. Call `search_places` with query="{what} in {where}" and limit=20.\n'
74
+ "2. Drop closed places and places with very few reviews; shortlist the most promising.\n"
75
+ "3. For each shortlisted place read one page of newest reviews (`get_reviews`, limit=20) "
76
+ "to check that recent experiences confirm the rating.\n"
77
+ f"4. Rank the top {how_many} with: name, rating and review count, address, one-line "
78
+ "verdict, and one recent quote. Mention any red flags.\n"
79
+ )
@@ -0,0 +1,170 @@
1
+ """MCP resources: static documentation exposed to AI clients."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from mcp.server.fastmcp import FastMCP
6
+
7
+
8
+ def register_resources(mcp: FastMCP) -> None:
9
+ """Register documentation resources on the MCP server."""
10
+
11
+ @mcp.resource("scrapemapsapi://docs/api-reference", mime_type="text/markdown")
12
+ async def api_reference() -> str:
13
+ """ScrapeMapsAPI REST API reference (endpoints, parameters, fields, errors)."""
14
+ return API_REFERENCE
15
+
16
+ @mcp.resource("scrapemapsapi://docs/quickstart", mime_type="text/markdown")
17
+ async def quickstart() -> str:
18
+ """Setting up the ScrapeMapsAPI MCP server."""
19
+ return QUICKSTART
20
+
21
+ @mcp.resource("scrapemapsapi://docs/pricing", mime_type="text/markdown")
22
+ async def pricing() -> str:
23
+ """Credit costs of each call."""
24
+ return PRICING
25
+
26
+ @mcp.resource("scrapemapsapi://docs/examples", mime_type="text/markdown")
27
+ async def examples() -> str:
28
+ """Common workflows with the tools."""
29
+ return EXAMPLES
30
+
31
+
32
+ API_REFERENCE = """\
33
+ # ScrapeMapsAPI API Reference
34
+
35
+ Base URL: `https://api.scrapemapsapi.com` (override with `SCRAPEMAPSAPI_BASE_URL`).
36
+ Authentication: `X-API-Key: <key>` header. JSON only. Lists use opaque cursors.
37
+
38
+ Every response is `{"data": ..., "meta": {"credits_used", "cached", ...}}`, plus
39
+ `"pagination": {"next_cursor", "has_more"}` for lists.
40
+ Headers: `X-Credits-Used`, `X-Credits-Remaining`, `X-Cache` (HIT/MISS).
41
+
42
+ A `place` is a place ID (`ChIJ...`), a CID (decimal, as in `maps?cid=`) or a feature ID
43
+ (`0x...:0x...`, URL-encoded in paths).
44
+
45
+ ## GET /v1/places/search
46
+ Text search, optionally biased to an area.
47
+
48
+ | Param | Default | Notes |
49
+ |---|---|---|
50
+ | q | (required) | e.g. `pizzeria in Naples` |
51
+ | language | en | e.g. `it`, `pt-BR` |
52
+ | region | us | 2-letter country code |
53
+ | lat, lng | | both or neither |
54
+ | radius_km | | up to 100, with lat/lng |
55
+ | limit | 20 | 1-20 (one page per call) |
56
+ | cursor | | `next_cursor` of the previous page |
57
+
58
+ `data` items (PlaceSummary): `id`, `ids {place_id, cid, feature_id, google_maps_url}`, `name`,
59
+ `categories`, `address {formatted, street, postal_code, city, region, country_code}`,
60
+ `location {lat, lng}`, `rating`, `review_count`, `phone`, `website`,
61
+ `status` (operational / temporarily_closed / permanently_closed / null).
62
+ `meta`: `credits_used`, `cached`, `query`, `language`, `region`.
63
+
64
+ ## GET /v1/places/{place}
65
+ Full details: PlaceSummary fields plus `local_name`, `phone_international`, `plus_code`,
66
+ `timezone`, `description`, `opening_hours {weekly: [{day, closed, open_24h, periods: [{open, close}],
67
+ text}], status_text}`, `attributes {group: [features]}`, `photos [{url, width, height}]`,
68
+ `booking_links [{url, domain}]`, `knowledge_graph_id`. Params: `language`, `region`.
69
+
70
+ ## GET /v1/places/{place}/reviews
71
+ | Param | Default | Notes |
72
+ |---|---|---|
73
+ | sort | relevant | relevant, newest, highest, lowest |
74
+ | language | en | also the translation target |
75
+ | original_language | | only reviews written in this language |
76
+ | limit | 20 | 1-20 (one page per call) |
77
+ | cursor | | `next_cursor` of the previous page |
78
+
79
+ `data` items (Review): `id`, `rating` (1-5), `published_at` (ISO 8601 UTC), `relative_date`,
80
+ `language`, `text`, `translated_text`, `author {id}` (pseudonymous; no names or photos),
81
+ `owner_response {text, translated_text, relative_date}`, `photos`, `details {question: answer}`,
82
+ `source`. `meta`: `credits_used`, `cached`, `place_id`, `cid`, `sort`, `language`, `original_language`.
83
+
84
+ ## GET /v1/places/resolve?input=
85
+ Converts a place ID, CID, feature ID or Google Maps URL (short links too) into
86
+ `{place_id, cid, feature_id, google_maps_url}`.
87
+
88
+ ## Errors
89
+ Body: `{"detail": {"error": "<code>", "message": "<text>"}}`. Errors are never billed.
90
+
91
+ | HTTP | Code | Meaning |
92
+ |---|---|---|
93
+ | 400 | invalid_place_id, invalid_cursor, invalid_location | bad identifier, cursor, or lat without lng |
94
+ | 401 | missing_api_key, invalid_api_key | |
95
+ | 402 | insufficient_credits | top up |
96
+ | 404 | place_not_found | |
97
+ | 422 | (validation) | parameter out of range |
98
+ | 429 | rate_limited, insufficient_credits_retry_later | see `Retry-After` |
99
+ | 502 | upstream_error | Google Maps error, retry later |
100
+ | 503 | upstream_unavailable | Google Maps unreachable, retry in a minute |
101
+ """
102
+
103
+ QUICKSTART = """\
104
+ # ScrapeMapsAPI MCP: Quick Start
105
+
106
+ 1. Create an API key at https://scrapemapsapi.com/dashboard/api-keys.
107
+ 2. Add the server to your MCP client (Claude Desktop, Cursor, Cline, ...):
108
+
109
+ ```json
110
+ {
111
+ "mcpServers": {
112
+ "scrapemapsapi": {
113
+ "command": "uvx",
114
+ "args": ["scrapemapsapi-mcp"],
115
+ "env": { "SCRAPEMAPSAPI_API_KEY": "your_api_key" }
116
+ }
117
+ }
118
+ }
119
+ ```
120
+
121
+ Alternatives: `npx -y scrapemapsapi-mcp` (needs uv or Python 3.10+), or
122
+ `pip install scrapemapsapi-mcp` and `"command": "scrapemapsapi-mcp"`.
123
+
124
+ 3. Ask, for example:
125
+ - "Find the best ramen places in Milan and check their recent reviews"
126
+ - "Summarize the reviews of https://maps.app.goo.gl/..."
127
+ - "What are the opening hours of Pizzeria Da Michele in Naples?"
128
+ """
129
+
130
+ PRICING = """\
131
+ # ScrapeMapsAPI Pricing
132
+
133
+ Every successful call costs 1 credit, whatever it returns:
134
+
135
+ | Call | Credits |
136
+ |---|---|
137
+ | search_places | 1 per call (one page, up to 20 places) |
138
+ | get_place | 1 |
139
+ | get_reviews | 1 per call (one page, up to 20 reviews) |
140
+ | resolve_place | 1 |
141
+
142
+ - The next page is a new call (1 credit). Errors cost nothing; an empty result is a call (1 credit).
143
+ - 200 free calls every month; then $3 per 1,000 calls, down to $1.50 with credit packs.
144
+ - Purchased credits are valid for 12 months from purchase.
145
+ - Each tool result shows the credits used and remaining.
146
+ - Top up at https://scrapemapsapi.com/dashboard/billing.
147
+ """
148
+
149
+ EXAMPLES = """\
150
+ # ScrapeMapsAPI: Common Workflows
151
+
152
+ ## Find places
153
+ `search_places(query="vegan restaurant in Berlin", limit=10)`; near a point:
154
+ `search_places(query="pharmacy", lat=45.4642, lng=9.19, radius_km=1)`.
155
+ Use the `ref` of a result with `get_place` / `get_reviews`.
156
+
157
+ ## From a Google Maps link
158
+ `resolve_place(input="https://maps.app.goo.gl/...")`, then `get_place(place=<place_id or cid>)`.
159
+
160
+ ## Read all the reviews
161
+ `get_reviews(place=..., sort="newest")` (20 per page), then call again with the returned `cursor`
162
+ until there are no more. Keep sort and filters the same while following a cursor.
163
+
164
+ ## Reviews in one language
165
+ `get_reviews(place=..., original_language="it", language="en")`: only reviews written in Italian,
166
+ shown translated to English.
167
+
168
+ ## Worst reviews first
169
+ `get_reviews(place=..., sort="lowest")` to see complaints quickly.
170
+ """
@@ -0,0 +1,61 @@
1
+ """ScrapeMapsAPI MCP server entry point."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import sys
7
+
8
+ from mcp.server.fastmcp import FastMCP
9
+
10
+ from .client import DEFAULT_BASE_URL, ScrapeMapsAPIClient
11
+ from .errors import API_KEYS_URL
12
+ from .prompts import register_prompts
13
+ from .resources import register_resources
14
+ from .tools import register_tools
15
+
16
+ API_KEY_ENV = "SCRAPEMAPSAPI_API_KEY"
17
+ BASE_URL_ENV = "SCRAPEMAPSAPI_BASE_URL"
18
+
19
+ mcp = FastMCP(
20
+ "ScrapeMapsAPI",
21
+ instructions=(
22
+ "Google Maps places and reviews via the ScrapeMapsAPI API. Use search_places to find places "
23
+ "by text (optionally near lat/lng), get_place for full details and opening hours, "
24
+ "get_reviews to read reviews page by page (follow the cursor; sort and language filters "
25
+ "available) and resolve_place to turn a Google Maps URL into place identifiers. "
26
+ "Calls cost credits: request only what the task needs."
27
+ ),
28
+ )
29
+
30
+ # Lazy-init client so import doesn't fail without env var (tests, --help, etc.)
31
+ _client: ScrapeMapsAPIClient | None = None
32
+
33
+
34
+ def _get_client() -> ScrapeMapsAPIClient:
35
+ global _client
36
+ if _client is None:
37
+ api_key = os.environ.get(API_KEY_ENV, "")
38
+ if not api_key:
39
+ print(
40
+ f"Error: {API_KEY_ENV} environment variable is required.\nGet your API key at {API_KEYS_URL}",
41
+ file=sys.stderr,
42
+ )
43
+ sys.exit(1)
44
+ base_url = os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
45
+ _client = ScrapeMapsAPIClient(api_key=api_key, base_url=base_url)
46
+ return _client
47
+
48
+
49
+ register_tools(mcp, _get_client)
50
+ register_resources(mcp)
51
+ register_prompts(mcp)
52
+
53
+
54
+ def main() -> None:
55
+ """Run the MCP server (stdio transport)."""
56
+ _get_client() # fail fast if the key is missing
57
+ mcp.run(transport="stdio")
58
+
59
+
60
+ if __name__ == "__main__":
61
+ main()
@@ -0,0 +1,333 @@
1
+ """MCP tools for ScrapeMapsAPI.
2
+
3
+ Responses are compact text for an LLM: the useful fields only, long texts capped, and every
4
+ identifier needed for the next call (place ID / CID, next cursor) spelled out.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Callable
10
+ from typing import Any, Literal, Optional
11
+
12
+ from mcp.server.fastmcp import FastMCP
13
+ from mcp.server.fastmcp.exceptions import ToolError
14
+ from mcp.types import ToolAnnotations
15
+
16
+ from .client import ApiResult, ScrapeMapsAPIClient
17
+ from .errors import ScrapeMapsAPIError
18
+
19
+ REVIEW_TEXT_MAX = 600
20
+ OWNER_RESPONSE_MAX = 200
21
+ DESCRIPTION_MAX = 600
22
+ ATTRIBUTE_GROUPS_MAX = 8
23
+ ATTRIBUTE_ITEMS_MAX = 8
24
+ PHOTOS_MAX = 3
25
+ SEARCH_LIMIT_MAX = 20
26
+ REVIEWS_LIMIT_MAX = 20 # one page of the review feed per call (the API maximum)
27
+
28
+ _DAY_ABBR = {
29
+ "monday": "Mon",
30
+ "tuesday": "Tue",
31
+ "wednesday": "Wed",
32
+ "thursday": "Thu",
33
+ "friday": "Fri",
34
+ "saturday": "Sat",
35
+ "sunday": "Sun",
36
+ }
37
+
38
+ READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=True)
39
+
40
+
41
+ def cap(text: Optional[str], limit: int) -> str:
42
+ """Collapse whitespace and cut to ``limit`` characters on a word boundary."""
43
+ if not text:
44
+ return ""
45
+ flat = " ".join(text.split())
46
+ if len(flat) <= limit:
47
+ return flat
48
+ cut = flat[:limit].rsplit(" ", 1)[0] if " " in flat[:limit] else flat[:limit]
49
+ return cut.rstrip(",.;:") + "…"
50
+
51
+
52
+ def place_ref(place: dict[str, Any]) -> str:
53
+ ids = place.get("ids") or {}
54
+ return place.get("id") or ids.get("place_id") or ids.get("cid") or "?"
55
+
56
+
57
+ def _rating(place: dict[str, Any]) -> str:
58
+ rating, count = place.get("rating"), place.get("review_count")
59
+ if rating is None:
60
+ return "no rating"
61
+ return f"{rating}★ ({count:,} reviews)" if isinstance(count, int) else f"{rating}★"
62
+
63
+
64
+ def _credits(result: ApiResult) -> str:
65
+ used = result.credits_used if result.credits_used is not None else result.meta.get("credits_used")
66
+ parts = []
67
+ if used is not None:
68
+ parts.append(f"credits used: {used}")
69
+ if result.credits_remaining is not None:
70
+ parts.append(f"remaining: {result.credits_remaining}")
71
+ return f"[{', '.join(parts)}]" if parts else ""
72
+
73
+
74
+ def _status(place: dict[str, Any]) -> str:
75
+ status = place.get("status")
76
+ return "" if status in (None, "operational") else status.replace("_", " ").upper()
77
+
78
+
79
+ def format_search(result: ApiResult, query: str) -> str:
80
+ places = result.data or []
81
+ if not places:
82
+ return f'No places found for "{query}". {_credits(result)}'.strip()
83
+ lines = [f'{len(places)} places for "{query}" {_credits(result)}'.rstrip()]
84
+ for i, p in enumerate(places, 1):
85
+ cats = ", ".join((p.get("categories") or [])[:3])
86
+ head = f"{i}. {p.get('name')} | {_rating(p)}"
87
+ if cats:
88
+ head += f" | {cats}"
89
+ if _status(p):
90
+ head += f" | {_status(p)}"
91
+ lines.append(head)
92
+ addr = (p.get("address") or {}).get("formatted")
93
+ if addr:
94
+ lines.append(f" {addr}")
95
+ extra = [f"ref: {place_ref(p)}"]
96
+ if p.get("phone"):
97
+ extra.append(f"phone: {p['phone']}")
98
+ if p.get("website"):
99
+ extra.append(f"web: {p['website']}")
100
+ lines.append(" " + " | ".join(extra))
101
+ cursor = result.pagination.get("next_cursor")
102
+ if result.pagination.get("has_more") and cursor:
103
+ lines.append(f'\nMore results: call search_places again with the same query and cursor="{cursor}".')
104
+ return "\n".join(lines)
105
+
106
+
107
+ def _hours(hours: dict[str, Any]) -> list[str]:
108
+ out = []
109
+ for day in hours.get("weekly") or []:
110
+ name = _DAY_ABBR.get(day.get("day", ""), day.get("day", "?"))
111
+ if day.get("closed"):
112
+ value = "closed"
113
+ elif day.get("open_24h"):
114
+ value = "open 24h"
115
+ elif day.get("periods"):
116
+ value = ", ".join(f"{p['open']}–{p['close']}" for p in day["periods"])
117
+ else:
118
+ value = day.get("text") or "?"
119
+ out.append(f"{name} {value}")
120
+ return out
121
+
122
+
123
+ def format_place(result: ApiResult) -> str:
124
+ p = result.data or {}
125
+ ids = p.get("ids") or {}
126
+ lines = [f"{p.get('name')} {_credits(result)}".rstrip()]
127
+ if p.get("local_name") and p.get("local_name") != p.get("name"):
128
+ lines.append(f"Local name: {p['local_name']}")
129
+ if p.get("categories"):
130
+ lines.append("Categories: " + ", ".join(p["categories"]))
131
+ lines.append(f"Rating: {_rating(p)}")
132
+ if _status(p):
133
+ lines.append(f"Status: {_status(p)}")
134
+ addr = (p.get("address") or {}).get("formatted")
135
+ if addr:
136
+ lines.append(f"Address: {addr}")
137
+ loc = p.get("location") or {}
138
+ if "lat" in loc:
139
+ lines.append(
140
+ f"Location: {loc['lat']}, {loc['lng']}" + (f" | plus code {p['plus_code']}" if p.get("plus_code") else "")
141
+ )
142
+ phone = p.get("phone_international") or p.get("phone")
143
+ if phone:
144
+ lines.append(f"Phone: {phone}")
145
+ if p.get("website"):
146
+ lines.append(f"Website: {p['website']}")
147
+ hours = p.get("opening_hours")
148
+ if hours:
149
+ status_text = f" ({hours['status_text']})" if hours.get("status_text") else ""
150
+ lines.append(f"Hours{status_text}: " + "; ".join(_hours(hours)))
151
+ if p.get("timezone"):
152
+ lines.append(f"Timezone: {p['timezone']}")
153
+ if p.get("description"):
154
+ lines.append(f"Description: {cap(p['description'], DESCRIPTION_MAX)}")
155
+ attributes = p.get("attributes") or {}
156
+ if attributes:
157
+ lines.append("Features:")
158
+ for group, items in list(attributes.items())[:ATTRIBUTE_GROUPS_MAX]:
159
+ more = f" (+{len(items) - ATTRIBUTE_ITEMS_MAX})" if len(items) > ATTRIBUTE_ITEMS_MAX else ""
160
+ lines.append(f"- {group}: {', '.join(items[:ATTRIBUTE_ITEMS_MAX])}{more}")
161
+ links = p.get("booking_links") or []
162
+ if links:
163
+ lines.append("Booking: " + ", ".join(link.get("domain") or link["url"] for link in links[:3]))
164
+ photos = p.get("photos") or []
165
+ if photos:
166
+ lines.append(f"Photos ({len(photos)}): " + " ".join(ph["url"] for ph in photos[:PHOTOS_MAX]))
167
+ lines.append(
168
+ f"IDs: place_id {ids.get('place_id') or '-'} | cid {ids.get('cid')} | feature_id {ids.get('feature_id')}"
169
+ )
170
+ if ids.get("google_maps_url"):
171
+ lines.append(f"Google Maps: {ids['google_maps_url']}")
172
+ return "\n".join(lines)
173
+
174
+
175
+ def format_review(r: dict[str, Any]) -> str:
176
+ rating = f"{r['rating']}★" if r.get("rating") else "no rating"
177
+ when = (r.get("published_at") or "")[:10] or r.get("relative_date") or "date unknown"
178
+ text = r.get("translated_text") or r.get("text")
179
+ lang = r.get("language")
180
+ translated = f" (translated from {lang})" if r.get("translated_text") and lang else ""
181
+ line = f"- {rating} | {when}{translated}: {cap(text, REVIEW_TEXT_MAX) if text else '(no text)'}"
182
+ details = r.get("details") or {}
183
+ if details:
184
+ line += "\n details: " + "; ".join(f"{k}: {v}" for k, v in list(details.items())[:6])
185
+ owner = r.get("owner_response")
186
+ if owner:
187
+ reply = owner.get("translated_text") or owner.get("text")
188
+ line += f"\n owner reply: {cap(reply, OWNER_RESPONSE_MAX)}"
189
+ return line
190
+
191
+
192
+ def format_reviews(result: ApiResult, place: str) -> str:
193
+ reviews = result.data or []
194
+ meta = result.meta
195
+ head = f"{len(reviews)} reviews of {place} (sort: {meta.get('sort', '?')}"
196
+ if meta.get("original_language"):
197
+ head += f", only written in {meta['original_language']}"
198
+ head += f") {_credits(result)}"
199
+ if not reviews:
200
+ return head.rstrip() + "\nNo reviews on this page."
201
+ lines = [head.rstrip()]
202
+ lines.extend(format_review(r) for r in reviews)
203
+ cursor = result.pagination.get("next_cursor")
204
+ if result.pagination.get("has_more") and cursor:
205
+ lines.append(f'\nMore reviews: call get_reviews with the same place, sort and filters and cursor="{cursor}".')
206
+ else:
207
+ lines.append("\nNo more reviews.")
208
+ return "\n".join(lines)
209
+
210
+
211
+ def format_resolve(result: ApiResult) -> str:
212
+ d = result.data or {}
213
+ return "\n".join(
214
+ [
215
+ f"Resolved {_credits(result)}".rstrip(),
216
+ f"place_id: {d.get('place_id') or '-'}",
217
+ f"cid: {d.get('cid')}",
218
+ f"feature_id: {d.get('feature_id')}",
219
+ f"google_maps_url: {d.get('google_maps_url')}",
220
+ ]
221
+ )
222
+
223
+
224
+ def register_tools(mcp: FastMCP, get_client: Callable[[], ScrapeMapsAPIClient]) -> None:
225
+ """Register all tools. API errors become ToolError (isError) with a readable message."""
226
+
227
+ @mcp.tool(annotations=READ_ONLY)
228
+ async def search_places(
229
+ query: str,
230
+ language: str = "en",
231
+ region: Optional[str] = None,
232
+ lat: Optional[float] = None,
233
+ lng: Optional[float] = None,
234
+ radius_km: Optional[float] = None,
235
+ limit: int = 20,
236
+ cursor: Optional[str] = None,
237
+ ) -> str:
238
+ """Search Google Maps places by text, e.g. "pizzeria in Naples" or "dentist near Brooklyn".
239
+
240
+ Returns name, rating, categories, address, phone, website and the `ref` to pass to
241
+ get_place / get_reviews. Costs 1 credit per call (up to 20 places).
242
+
243
+ Args:
244
+ query: What to search, ideally with the area ("coffee in Milan").
245
+ language: Language of the results, e.g. 'en', 'it', 'pt-BR'.
246
+ region: 2-letter country code that biases results, e.g. 'it', 'us'.
247
+ lat: Latitude of the area centre (use together with lng).
248
+ lng: Longitude of the area centre (use together with lat).
249
+ radius_km: Area radius in km around lat/lng (max 100).
250
+ limit: Places to return, 1-20 (default 20, same cost).
251
+ cursor: `cursor` value from a previous search_places result, for the next page.
252
+ """
253
+ if (lat is None) != (lng is None):
254
+ raise ToolError("Provide both lat and lng, or neither.")
255
+ try:
256
+ result = await get_client().search(
257
+ query,
258
+ language=language,
259
+ region=region,
260
+ lat=lat,
261
+ lng=lng,
262
+ radius_km=radius_km,
263
+ limit=max(1, min(limit, SEARCH_LIMIT_MAX)),
264
+ cursor=cursor,
265
+ )
266
+ except ScrapeMapsAPIError as e:
267
+ raise ToolError(e.for_tool()) from e
268
+ return format_search(result, query)
269
+
270
+ @mcp.tool(annotations=READ_ONLY)
271
+ async def get_place(place: str, language: str = "en", region: Optional[str] = None) -> str:
272
+ """Full details of a Google Maps place: address, phone, website, opening hours,
273
+ description, features, photos and all its identifiers. Costs 1 credit.
274
+
275
+ Args:
276
+ place: Place ID (ChIJ...), CID (digits) or feature ID (0x...:0x...). For a Google
277
+ Maps URL call resolve_place first.
278
+ language: Language of the results, e.g. 'en', 'it'.
279
+ region: 2-letter country code, e.g. 'it', 'us'.
280
+ """
281
+ try:
282
+ result = await get_client().get_place(place, language=language, region=region)
283
+ except ScrapeMapsAPIError as e:
284
+ raise ToolError(e.for_tool()) from e
285
+ return format_place(result)
286
+
287
+ @mcp.tool(annotations=READ_ONLY)
288
+ async def get_reviews(
289
+ place: str,
290
+ sort: Literal["relevant", "newest", "highest", "lowest"] = "relevant",
291
+ language: str = "en",
292
+ original_language: Optional[str] = None,
293
+ limit: int = 20,
294
+ cursor: Optional[str] = None,
295
+ ) -> str:
296
+ """Reviews of a Google Maps place, one page at a time (all reviews are reachable by
297
+ following the cursor). Texts are shown translated into `language` when Google provides a
298
+ translation, and capped at 600 characters. Costs 1 credit per call (up to 20 reviews).
299
+
300
+ Args:
301
+ place: Place ID (ChIJ...), CID (digits) or feature ID (0x...:0x...).
302
+ sort: 'relevant' (default), 'newest', 'highest' or 'lowest' rating first.
303
+ language: Language to translate reviews into, e.g. 'en'.
304
+ original_language: Only reviews originally written in this language, e.g. 'it'.
305
+ limit: Reviews per page, 1-20 (default 20, same cost).
306
+ cursor: `cursor` value from a previous get_reviews result (same place, sort and filters).
307
+ """
308
+ try:
309
+ result = await get_client().get_reviews(
310
+ place,
311
+ sort=sort,
312
+ language=language,
313
+ original_language=original_language,
314
+ limit=max(1, min(limit, REVIEWS_LIMIT_MAX)),
315
+ cursor=cursor,
316
+ )
317
+ except ScrapeMapsAPIError as e:
318
+ raise ToolError(e.for_tool()) from e
319
+ return format_reviews(result, place)
320
+
321
+ @mcp.tool(annotations=READ_ONLY)
322
+ async def resolve_place(input: str) -> str:
323
+ """Convert a Google Maps URL (including maps.app.goo.gl short links), place ID, CID or
324
+ feature ID into all identifiers of the place. Costs 1 credit.
325
+
326
+ Args:
327
+ input: A Google Maps URL or any place identifier.
328
+ """
329
+ try:
330
+ result = await get_client().resolve(input)
331
+ except ScrapeMapsAPIError as e:
332
+ raise ToolError(e.for_tool()) from e
333
+ return format_resolve(result)
@@ -0,0 +1,150 @@
1
+ Metadata-Version: 2.5
2
+ Name: scrapemapsapi-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for the ScrapeMapsAPI API: Google Maps places, details and reviews for AI assistants
5
+ Project-URL: Homepage, https://scrapemapsapi.com
6
+ Project-URL: Repository, https://github.com/scrapemapsapi/mcp-server
7
+ Project-URL: Issues, https://github.com/scrapemapsapi/mcp-server/issues
8
+ Project-URL: Documentation, https://scrapemapsapi.com/docs/mcp
9
+ Author: ScrapeMapsAPI
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: ai,google-maps,llm,mcp,places,reviews
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Requires-Python: >=3.10
21
+ Requires-Dist: httpx<1,>=0.27
22
+ Requires-Dist: mcp[cli]<2,>=1.10
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
25
+ Requires-Dist: pytest>=8.0; extra == 'dev'
26
+ Requires-Dist: respx>=0.22; extra == 'dev'
27
+ Requires-Dist: ruff>=0.6; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # ScrapeMapsAPI MCP Server
31
+
32
+ <!-- mcp-name: com.scrapemapsapi/scrapemapsapi -->
33
+
34
+ An [MCP](https://modelcontextprotocol.io) server that gives AI assistants (Claude Desktop, Claude Code, Cursor, Cline, ...) access to Google Maps places, place details and **all** the reviews of a place, via the [ScrapeMapsAPI](https://scrapemapsapi.com) API.
35
+
36
+ ## No install: connect from Claude or ChatGPT
37
+
38
+ ScrapeMapsAPI also runs as a **remote MCP server** with OAuth sign-in, so you can use the same tools from
39
+ Claude (claude.ai, Desktop, mobile), ChatGPT or any client that supports remote servers, without an API key or
40
+ anything to install:
41
+
42
+ ```
43
+ https://api.scrapemapsapi.com/mcp
44
+ ```
45
+
46
+ - **Claude**: Customize → Connectors → + Add → Add custom connector, paste the URL, then sign in with your
47
+ ScrapeMapsAPI account and allow access.
48
+ - **ChatGPT**: chatgpt.com/plugins → + → Add custom MCP server, paste the URL as Server URL, OAuth authentication.
49
+ - **Claude Code**: `claude mcp add --transport http scrapemapsapi https://api.scrapemapsapi.com/mcp`, then `/mcp`
50
+ to sign in.
51
+
52
+ Calls use your account's credits exactly like the API; see or disconnect connected apps in Dashboard → Connected
53
+ apps. Step-by-step guide: https://scrapemapsapi.com/docs/mcp. The package below is the **local** server (stdio,
54
+ API key), for developers who prefer to run it themselves; both offer the same tools, prompts and resources.
55
+
56
+ ## Features
57
+
58
+ **4 tools**: `search_places`, `get_place`, `get_reviews`, `resolve_place`. Results are compact text built for LLMs: the useful fields only, long texts capped, and the identifiers and cursors needed for the next call.
59
+
60
+ **4 documentation resources**: API reference, quickstart, pricing, workflow examples.
61
+
62
+ **3 prompts**: summarize the reviews of a place, compare places, find the best places of a kind in an area.
63
+
64
+ ## Quick start
65
+
66
+ ### 1. Get an API key
67
+
68
+ Create one at [scrapemapsapi.com](https://scrapemapsapi.com/dashboard/api-keys).
69
+
70
+ ### 2. Configure your client
71
+
72
+ Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`), Cline and most other clients:
73
+
74
+ ```json
75
+ {
76
+ "mcpServers": {
77
+ "scrapemapsapi": {
78
+ "command": "uvx",
79
+ "args": ["scrapemapsapi-mcp"],
80
+ "env": {
81
+ "SCRAPEMAPSAPI_API_KEY": "your_api_key"
82
+ }
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ Claude Code:
89
+
90
+ ```bash
91
+ claude mcp add scrapemapsapi -e SCRAPEMAPSAPI_API_KEY=your_api_key -- uvx scrapemapsapi-mcp
92
+ ```
93
+
94
+ ### 3. Use it
95
+
96
+ - "Find the five best-rated ramen places in Milan and check what recent reviews say"
97
+ - "Summarize the reviews of https://maps.app.goo.gl/..."
98
+ - "Show me the one-star reviews of Pizzeria Da Michele in Naples, written in Italian"
99
+ - "Is the Louvre open on Monday?"
100
+
101
+ ## Tools
102
+
103
+ | Tool | What it does | Credits |
104
+ |------|-------------|---------|
105
+ | `search_places` | Text search, optionally near `lat`/`lng` within `radius_km`; `limit` 1-20 (default 20), `cursor` for more | 1 per call |
106
+ | `get_place` | Details: address, phone, website, opening hours, description, features, photos, IDs | 1 |
107
+ | `get_reviews` | One page of reviews; `sort` relevant/newest/highest/lowest, `language` (translation target), `original_language` filter, `limit` 1-20, `cursor` | 1 per call |
108
+ | `resolve_place` | Google Maps URL (short links too), place ID, CID or feature ID into every identifier | 1 |
109
+
110
+ Places are identified by a place ID (`ChIJ...`), a CID (digits) or a feature ID (`0x...:0x...`). Review texts are capped at 600 characters and owner replies at 200. API errors are returned as tool errors with a readable message and what to do next (e.g. top up credits, use `resolve_place`).
111
+
112
+ ## Installation alternatives
113
+
114
+ ```bash
115
+ # pip
116
+ pip install scrapemapsapi-mcp
117
+ SCRAPEMAPSAPI_API_KEY=... scrapemapsapi-mcp
118
+
119
+ # npx (wraps uvx, or python3 -m as a fallback)
120
+ SCRAPEMAPSAPI_API_KEY=... npx -y scrapemapsapi-mcp
121
+
122
+ # Docker
123
+ docker build -t scrapemapsapi-mcp . && docker run -i --rm -e SCRAPEMAPSAPI_API_KEY=... scrapemapsapi-mcp
124
+ ```
125
+
126
+ ## Environment variables
127
+
128
+ | Variable | Required | Description |
129
+ |----------|----------|-------------|
130
+ | `SCRAPEMAPSAPI_API_KEY` | Yes | Your API key |
131
+ | `SCRAPEMAPSAPI_BASE_URL` | No | Override the API base URL (default `https://api.scrapemapsapi.com`), e.g. `http://localhost:8000` |
132
+
133
+ ## Development
134
+
135
+ ```bash
136
+ cd sdks/mcp
137
+ uv venv && uv pip install -e ".[dev]"
138
+ .venv/bin/pytest
139
+ .venv/bin/ruff check .
140
+ ```
141
+
142
+ Test with the MCP Inspector:
143
+
144
+ ```bash
145
+ SCRAPEMAPSAPI_API_KEY=... SCRAPEMAPSAPI_BASE_URL=http://localhost:8000 uv run mcp dev dev_server.py
146
+ ```
147
+
148
+ ## License
149
+
150
+ MIT
@@ -0,0 +1,12 @@
1
+ scrapemapsapi_mcp/__init__.py,sha256=9JbdWZ6XxZ1Os2kwGQG_KOuVJFIuzeO2FKDtuArej18,111
2
+ scrapemapsapi_mcp/client.py,sha256=hhY0-0Cf9fD4o9VnQ21Oow6_iTNV4tO1boLgjL-4Ec8,5567
3
+ scrapemapsapi_mcp/errors.py,sha256=tmW4TU5yV3O9qWJcfzpVaFBRpe3siouN7chdPCsSjk0,5132
4
+ scrapemapsapi_mcp/prompts.py,sha256=H9wTH6RHp6ktqhfb_xS10qk8oDZ7mQYuALcrba1CoR0,4232
5
+ scrapemapsapi_mcp/resources.py,sha256=9B1nK6CJo9ZEMWdJFG4En7GghOhco2REuFSetGBYSI0,6544
6
+ scrapemapsapi_mcp/server.py,sha256=-Xbw5RnvxY-2OOiZ1KdSCBZlhdN-p7oGKRR2Fx9sf2M,1860
7
+ scrapemapsapi_mcp/tools.py,sha256=ZIW5JZEPOV4oL2RPEY1c7dHgNz4CvRo3fkJRBs0MHsY,13342
8
+ scrapemapsapi_mcp-0.1.0.dist-info/METADATA,sha256=y0zWnflUO-J6H-fZmDYdFrKJ00c5glVKpwi3710gpHM,5699
9
+ scrapemapsapi_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
10
+ scrapemapsapi_mcp-0.1.0.dist-info/entry_points.txt,sha256=Y-NDLiP6K5pA3lv5xekKo7FI_-flLLlSUUAAK8QPAS4,68
11
+ scrapemapsapi_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=1dsbsVLHmXs6w1JpPokMVYINQM44XsRS5V0lhJqYCd0,1070
12
+ scrapemapsapi_mcp-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ scrapemapsapi-mcp = scrapemapsapi_mcp.server:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 ScrapeMapsAPI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.