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.
- scrapemapsapi_mcp/__init__.py +3 -0
- scrapemapsapi_mcp/client.py +167 -0
- scrapemapsapi_mcp/errors.py +148 -0
- scrapemapsapi_mcp/prompts.py +79 -0
- scrapemapsapi_mcp/resources.py +170 -0
- scrapemapsapi_mcp/server.py +61 -0
- scrapemapsapi_mcp/tools.py +333 -0
- scrapemapsapi_mcp-0.1.0.dist-info/METADATA +150 -0
- scrapemapsapi_mcp-0.1.0.dist-info/RECORD +12 -0
- scrapemapsapi_mcp-0.1.0.dist-info/WHEEL +4 -0
- scrapemapsapi_mcp-0.1.0.dist-info/entry_points.txt +2 -0
- scrapemapsapi_mcp-0.1.0.dist-info/licenses/LICENSE +21 -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,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.
|