MCPFerramentas MCP/Localizações
Localizações
Crie, leia, atualize, arquive e verifique localizações, incluindo suas mídias.
- Readlist_locationsList a client's business locations with name, address, category, tags, status, verification, pending changes, and publisher connections. Starting point for any location-specific work. Each row has a `kind`: 'location' is a physical business; 'website' is a brand's website (e.g. synup.com) tracked for reviews, SEO, AEO and social only — it has no address, category, listings or Google Business Profile, so never publish, verify or edit listing fields on it, and call it a website, not a location.
- Readget_location_by_idGet the full details of a single location by its id. Use this once you know which location you want — typically after list_locations gives you the id — when the list summary isn't enough. Returns everything about that one location: full business profile (name, address, coordinates, phone(s), website, email, description, tagline), categories (general + per-publisher), hours (regular, special, and more-hours), attributes, services, menu, media, social links, service area, any per-publisher overrides, which publishers it's connected to, its verification status, and when it was last edited. IMPORTANT: for a location migrated from the legacy Synup platform, the `id` on the returned location can differ from the id you passed in — both values work everywhere a location id is accepted (here, update_location, etc.), but they won't be equal as strings. To compare or join locations use `nativeId` — the canonical id, the same value list_locations returns as `id`, present on every location — and `legacyId` is the legacy Synup id (null for locations created natively). You don't pass an agency — it comes from your credentials, and a location from another agency is never returned. To look up or find a location id first, use list_locations.
- Writecreate_locationCreate a new business location — or, with kind="website", a website entity — under a client or on its own. Pass the client's id (find it with list_clients) to add it to that client, or omit clientId to add it without a client. You must provide the location's business name, its two-letter country code (ISO-3166-1 alpha-2), and SOME category — creation fails without one, even though the schema can't mark it required (pass at least categoryName, from list_categories, or publisherCategories.google, from list_publisher_categories). Everything else — address, phone, website, description — is optional but makes for a better listing. Categories come in two kinds: one general category (look it up with list_categories) and per-publisher categories for Google, Facebook, Apple, and Bing (look them up with list_publisher_categories); resolve those first and pass their ids. Once created, the location is automatically queued for submission to online directories and listings. If latitude/longitude are omitted they're derived from the address. Returns the new location's id. You don't pass an agency — it comes from your credentials.
- Writeupdate_locationUpdate an existing location's business details — including its categories (general, Google primary, and additional), Google Business Profile attributes, and its service/product list. Identify the location by its locationId (the locationId returned by create_location). Pass only the fields you want to change — anything you omit is left as-is, and passing a field replaces its current value (pass an empty string to clear a text field, or the full new list to replace a list — except `name`, which can be renamed but never cleared, because a location with no name is rejected by every directory and fails to publish silently). The country can't be changed after a location is created. If you change the address without also passing coordinates, latitude/longitude are re-derived automatically. By default your change updates the shared details that every publisher inherits; to change a value for specific publishers only (e.g. a different description on Google vs. Facebook), pass applyToPublishers. Use specialHours for one-off date closures/hours (e.g. "mark this Sunday, Aug 2 2026, as closed") — any calendar date works, not just named holidays; use regularHours/moreHours for the standing weekly schedule and extra hour types. Saving queues the change to sync out to the connected directories automatically — it goes out about 15 minutes after the location's last edit (further edits in that window are batched into one sync), and a publisher-specific change (applyToPublishers) resubmits to just those publishers. Tell the user their change is saved and will sync out shortly, not that it is already live; use publish_location to push it to Google immediately. Returns the updated location. You don't pass an agency — it comes from your credentials. IN A CLIENT-PORTAL SESSION only the fields the portal itself exposes are writable; categories, publisher overrides, custom attributes, keywords, tags and UTM are REJECTED and named back to you in `rejected`. Tell the client which fields could not be changed and that their agency owns those — do not report a partial save as a complete one.
- Readget_location_mediaGet all of a single location's photos, grouped by category (COVER, LOGO, INTERIOR, etc.), plus the logo URL and a count summary. Use this to see what imagery a location currently has before uploading or deleting. Identify the location by its locationId (from list_locations or create_location). You don't pass an agency — it comes from your credentials.
- Readlist_location_mediaList locations together with their photos, newest first. Same filters as list_locations (client, status, tags, categories, verification, search, created range) — use it to answer things like "which locations have no photos?" or "show the media for this client's active locations". Each row has the location's id, name, logo, full media grouped by category, and a photo count. Returns up to 100 per page with a `nextCursor` for more. You don't pass an agency — it comes from your credentials.
- Writeupload_location_mediaAdd one or more photos to a location, in a given category. Provide each image as a public https URL (we fetch and re-host it) or as base64 bytes. Only images are supported (jpeg, png, gif, webp), max 5 MB each. The LOGO category holds a single logo — uploading to LOGO replaces the current logo. All other categories append. Saved photos are automatically queued to publish to Google. You don't pass an agency — it comes from your credentials.
- Writedelete_location_mediaRemove photos from a location. Pass `urls` to delete specific photos, or `category` to clear a whole category. The logo cannot be deleted — upload a new LOGO image to replace it instead. This removes the photos in the app; note it does not delete them from Google. You don't pass an agency — it comes from your credentials.
- Writearchive_locationSCHEDULE a location to be archived at the end of the current billing period, or restore an archived one. Archiving is deferred, not immediate: the location stays fully active — and still counts against the plan's location limit — until the period the customer has already paid for ends, then it is archived automatically and stops being billed. Because the slot is still occupied, scheduling does NOT free room to add another location until after it archives. Pass archived: false to restore an already-archived location. Use cancel_scheduled_archive to call off a pending archival.
- Writecancel_scheduled_archiveCall off a pending archival, so a location scheduled to archive at the end of the billing period carries on as normal. Only works while the archival is still pending — once the period has ended and the location is actually archived, use archive_location with archived: false to restore it instead.
- Writepublish_locationPush a location's current business details out to its connected Google Business Profile. Use this after update_location if you want to force an immediate Google sync rather than waiting for the automatic queue (which sends edits about 15 minutes after the last change). Idempotent — safe to call repeatedly. Returns the push result including any per-field errors Google reported — or, if the location has no Google account connected, `{ skipped: "<reason>" }` instead (nothing to push to, not an error).
- Writebulk_update_locationsApply the same profile patch, publisher overrides, and/or tag add/remove to many locations at once, optionally publishing each to Google afterward. Useful for changes like "add the tag 'holiday-hours-2026' to these 40 locations" or "turn off online ordering everywhere in this client". Up to 100 locations per call: the first 100 are applied and every extra id comes back in `results` as `{ ok: false, status: "skipped_over_limit" }` (also counted in `skipped`) — send those in another call, and never read a response with skipped > 0 as "all done". Tags are merged per-location (added/removed against each location's existing tags), never wholesale replaced. Returns a per-location result so partial failures are visible.
- Readget_location_verification_statusCheck a location's Google verification status and available verification methods. Returns connected:false if no Google account is linked. When connected, returns the current verification state (verified / pending / status) and the verification options Google currently offers for this listing (email, phone call, SMS, postcard, etc.) — use these to choose a method for verify_location.
- Writeverify_locationStart or complete Google verification for a location. To start: pass method (from get_location_verification_status's options — e.g. "EMAIL", "PHONE_CALL", "SMS", "ADDRESS") plus whichever of emailAddress/phoneNumber/mailerContact that method needs. To complete a pending verification once the PIN arrives: pass pin instead. The location must already be connected to a Google account (get_location_verification_status returns connected:false otherwise).
- Readlist_location_tag_recordsList location tags with their IDs, names and owning clients. Optionally filter one client; otherwise only accessible clients are included. Use these IDs to rename or delete tags. Requires an active agency user with Clients access.
- Writecreate_location_tagCreate a client-owned location tag or return the existing tag of the same name. Does not assign any locations. Requires Clients access and access to the client.
- Writerename_location_tagRename a client-owned location tag without changing its assignments. Duplicate names for the same client are refused. Requires Clients access and access to the owning client.
- Writedelete_location_tagDelete a location tag and all of its assignments. Returns locationsUnassigned so the impact is visible. Requires Clients access and access to the owning client.
- Readget_google_category_metadataRead Google's public category attributes or service types. Pass categoryId for attributes, or serviceTypes (category ID) and name (display name) for service types. region defaults to US. Uncached results require a connected Google account. This does not collect customer data or return credentials. Requires Clients access.
- Writepublish_location_nowQueue the stored location profile through the full listing publishing pipeline immediately. Uses the same publisher selection, restrictions and content checks as the app. Returns queued:true when accepted; queued:false with skipped:no_changes when no version changed since publishing. Queue acceptance is not confirmation of publisher completion. Requires Clients access.
- Readcheck_location_contentPreview content checks for a location edit without saving or publishing it. Pass patch and optional applyTo publisher selection; classify:false checks publisher requirements while guidelines remain pending. Returns report:null when checks are disabled, the entity is a website, or no checked field is changed. Never authorizes bypassing a content check. Requires Clients access.
- Writebulk_edit_locationsApply profile patches, publisher overrides, tag changes and optional immediate Google publishing to up to 100 locations. Accepts up to 1,000 IDs but returns overflow as skipped_over_limit. All processed targets must be accessible before any writes. Content checks hold the whole batch; subsequent per-location failures are reported individually. Requires Clients access.
- Readpreview_location_client_migrationPreview moving up to 500 locations to a managed client, including effects on shared menus, assets and connections. Returns a signed plan token valid for 15 minutes, bound to this user and selection. Review the effects before starting. Requires an owner/admin and agency-wide credentials.
- Writestart_location_client_migrationStart the exact client migration from a reviewed preview, passing its signed token and identical target/locations. A stale or changed plan is refused; preview again rather than bypassing the refusal. Returns a jobId, not completion. Requires the same owner/admin and agency-wide credentials.
- Readget_location_client_migrationRead the progress and failed-location reasons of a client migration job started by this user. Reports moved, failed and skipped counts; never treats queued or partial work as completed. Requires an owner/admin and agency-wide credentials.
- Writeduplicate_locationCreate a draft copy of a physical location's identity for the same client. Active identity duplicates are refused; archived sources without an active replacement can be copied. Does not submit listings. Respects location capacity and source identity checks. A standalone source creates a new standalone client and requires agency-wide credentials. Requires Clients access.
- Writedelete_locationPermanently delete an already archived location and its location-bound connections. Refuses active locations: use the existing archival workflow first. Requires Clients access and permission for the owning client. This is not a way to delete a publisher's live listing.