MewCP Google Business MCP

Lista os locais da conta especificada, opcionalmente filtrados e ordenados, e retorna os objetos Location correspondentes com informações de paginação.

Entradas:

- `parent` (string, required) — The name of the account to fetch locations from. If the parent Account is of type PERSONAL, only directly-owned Locations are returned; otherwise all accessible locations (direct or indirect) are returned.
- `read_mask` (string, required) — Comma-separated list of fully qualified field names to return. Example: "user.displayName,photo".
- `page_size` (integer, optional) — How many locations to fetch per page. Default 10, minimum 1, maximum 100.
- `page_token` (string, optional) — Fetches the next page; returned by a previous call when more locations exist than fit the page size.
- `filter_` (string, optional) — Filter constraining which locations to return. Empty means no constraints (all locations, paginated). See Google's "Work with Location Data" guide for valid fields.
- `order_by` (string, optional) — Comma-separated sort fields (SQL syntax). Default ascending; append " desc" for descending. Valid fields: title, storeCode. E.g. "title, storeCode desc".

Esquema de saída data:

{
  locations: {
    name: string;
    languageCode: string | null;
    storeCode: string | null;
    title: string | null;
    phoneNumbers: object | null;
    categories: object | null;
    storefrontAddress: object | null;
    websiteUri: string | null;
    regularHours: object | null;
    specialHours: object | null;
    serviceArea: object | null;
    labels: any[] | null;
    adWordsLocationExtensions: object | null;
    latlng: object | null;
    openInfo: object | null;
    metadata: object | null;
    profile: object | null;
    relationshipData: object | null;
    moreHours: any[] | null;
    serviceItems: any[] | null;
  }[];
  nextPageToken: string | null;
  totalSize: number | null;
}

Cria um novo Location que será de propriedade do usuário conectado e retorna o Location recém-criado.

Entradas:

- `parent` (string, required) — The name of the account in which to create this location.
- `location` (object, required) — Location object to create. Required sub-fields: title (and primaryCategory within categories if categories are set).
- `validate_only` (boolean, optional) — If true, validates the request without actually creating the location.
- `request_id` (string, optional) — A unique request ID for the server to detect duplicate requests. UUIDs recommended. Max 50 characters.

Esquema de saída data:

{
  name: string;
  languageCode: string | null;
  storeCode: string | null;
  title: string | null;
  phoneNumbers: object | null;
  categories: object | null;
  storefrontAddress: object | null;
  websiteUri: string | null;
  regularHours: object | null;
  specialHours: object | null;
  serviceArea: object | null;
  labels: any[] | null;
  adWordsLocationExtensions: object | null;
  latlng: object | null;
  openInfo: object | null;
  metadata: object | null;
  profile: object | null;
  relationshipData: object | null;
  moreHours: any[] | null;
  serviceItems: any[] | null;
}

Retorna o local especificado conforme definido pela última vez pelo comerciante; pode não refletir atualizações do Google ou conteúdo gerado pelo usuário ao vivo no Google Maps.

Entradas:

- `name` (string, required) — The name of the location to fetch.
- `read_mask` (string, required) — Read mask specifying which fields to return in the response. Comma-separated list of fully qualified field names. Example: "title,websiteUri".

Esquema de saída data:

{
  name: string;
  languageCode: string | null;
  storeCode: string | null;
  title: string | null;
  phoneNumbers: object | null;
  categories: object | null;
  storefrontAddress: object | null;
  websiteUri: string | null;
  regularHours: object | null;
  specialHours: object | null;
  serviceArea: object | null;
  labels: any[] | null;
  adWordsLocationExtensions: object | null;
  latlng: object | null;
  openInfo: object | null;
  metadata: object | null;
  profile: object | null;
  relationshipData: object | null;
  moreHours: any[] | null;
  serviceItems: any[] | null;
}

Atualiza os campos do local especificado de acordo com a máscara de atualização fornecida e retorna o Location atualizado. Apenas os campos fornecidos são alterados — os demais mantêm seu valor atual. OBSERVAÇÃO: isso sobrescreve os valores atuais dos campos — o estado original não é armazenado após a chamada. A resposta inclui tanto o estado antes quanto o depois, para que você tenha um registro completo do que mudou.

Entradas:

- `location_name` (string, required) — Google identifier for this location, in the form locations/{locationId}.
- `update_mask` (string, required) — The specific fields to update. Comma-separated list of fully qualified field names.
- `location` (object, required) — Location object carrying the updated field values.
- `validate_only` (boolean, optional) — If true, validates the request without actually updating; response is empty unless there are validation errors.

Esquema de saída data:

{
  before: {
    name: string;
    languageCode: string | null;
    storeCode: string | null;
    title: string | null;
    phoneNumbers: object | null;
    categories: object | null;
    storefrontAddress: object | null;
    websiteUri: string | null;
    regularHours: object | null;
    specialHours: object | null;
    serviceArea: object | null;
    labels: any[] | null;
    adWordsLocationExtensions: object | null;
    latlng: object | null;
    openInfo: object | null;
    metadata: object | null;
    profile: object | null;
    relationshipData: object | null;
    moreHours: any[] | null;
    serviceItems: any[] | null;
  };
  after: {
    name: string;
    languageCode: string | null;
    storeCode: string | null;
    title: string | null;
    phoneNumbers: object | null;
    categories: object | null;
    storefrontAddress: object | null;
    websiteUri: string | null;
    regularHours: object | null;
    specialHours: object | null;
    serviceArea: object | null;
    labels: any[] | null;
    adWordsLocationExtensions: object | null;
    latlng: object | null;
    openInfo: object | null;
    metadata: object | null;
    profile: object | null;
    relationshipData: object | null;
    moreHours: any[] | null;
    serviceItems: any[] | null;
  };
}

DESTRUTIVO — REQUER CONFIRMAÇÃO EXPLÍCITA DO USUÁRIO ANTES DE CHAMAR. Exclui permanentemente o local. Esta ação é irreversível — o local e seus dados não podem ser recuperados por meio desta API (o site do Google Business Profile pode oferecer outros caminhos de recuperação). NUNCA chame esta ferramenta de forma autônoma ou como parte de um fluxo automatizado. Você DEVE parar, informar ao usuário exatamente o que será excluído e que isso é permanente, e aguardar a confirmação escrita explícita antes de prosseguir.

Entradas:

- `name` (string, required) — The name of the location to delete.

Esquema de saída data:

{
  // no fields — deletion is confirmed by the envelope's success/statusCode
}

Retorna o local especificado como ele aparece ao vivo no Google Maps e na Pesquisa, que pode diferir da versão do comerciante, juntamente com máscaras do que o Google alterou e do que ainda está pendente.

Entradas:

- `name` (string, required) — The name of the location to fetch.
- `read_mask` (string, required) — Comma-separated list of fully qualified field names to return.

Esquema de saída data:

{
  location: object;
  diffMask: string | null;
  pendingMask: string | null;
}

Recupera os atributos de um local conforme definidos pela última vez pelo comerciante.

Entradas:

- `name` (string, required) — Google identifier for this location, in the form locations/{locationId}/attributes.

Esquema de saída data:

{
  name: string;
  attributes: {
    name: string;
    valueType: string | null;
    values: any[] | null;
    repeatedEnumValue: object | null;
    uriValues: any[] | null;
  }[];
}

Atualiza os atributos de um determinado local de acordo com a máscara de atributos fornecida e retorna os Attributes atualizados. Apenas os campos fornecidos são alterados — os demais mantêm seu valor atual. OBSERVAÇÃO: isso sobrescreve os valores atuais dos campos — o estado original não é armazenado após a chamada. A resposta inclui tanto o estado antes quanto o depois, para que você tenha um registro completo do que mudou.

Entradas:

- `attributes_name` (string, required) — Google identifier for this location, in the form locations/{locationId}/attributes.
- `attribute_mask` (string, required) — Attribute names (as attributes/{attribute}) to update. Every attribute you want updated must be in both attributes and attributeMask. To delete an attribute, put it in attributeMask with no matching entry in attributes.
- `name` (string, required) — Google identifier for this location, in the form locations/{locationId}/attributes (body field, same value as attributes.name).
- `attributes` (array<object>, optional) — The attributes to set (each with name, valueType, values, repeatedEnumValue, uriValues). May be empty when deleting all attributes via attributeMask.

Esquema de saída data:

{
  before: {
    name: string;
    attributes: {
      name: string;
      valueType: string | null;
      values: any[] | null;
      repeatedEnumValue: object | null;
      uriValues: any[] | null;
    }[];
  };
  after: {
    name: string;
    attributes: {
      name: string;
      valueType: string | null;
      values: any[] | null;
      repeatedEnumValue: object | null;
      uriValues: any[] | null;
    }[];
  };
}

Recupera os atributos de um local como eles aparecem ao vivo no Google Maps e na Pesquisa, que podem diferir da versão do comerciante.

Entradas:

- `name` (string, required) — Google identifier for this location, in the form locations/{locationId}/attributes.

Esquema de saída data:

{
  name: string;
  attributes: {
    name: string;
    valueType: string | null;
    values: any[] | null;
    repeatedEnumValue: object | null;
    uriValues: any[] | null;
  }[];
}

Obtém a cadeia especificada, retornando NOT_FOUND se a cadeia não existir.

Entradas:

- `name` (string, required) — The chain's resource name, in the format `chains/{chain_place_id}`.

Esquema de saída data:

{
  name: string;
  chainNames: {
    displayName: string | null;
    languageCode: string | null;
  }[] | null;
  websites: {
    uri: string | null;
  }[] | null;
  locationCount: number | null;
}

Pesquisa uma cadeia com base no nome da cadeia e retorna a lista de cadeias correspondentes.

Entradas:

- `chain_name` (string, required) — Search for a chain by its name. Exact/partial/fuzzy/related queries are supported. Examples: "walmart", "wal-mart", "walmmmart", "沃尔玛".
- `page_size` (integer, optional, default: 10) — The maximum number of matched chains to return from this query. Default is 10, maximum is 500.

Esquema de saída data:

{
  chains: {
    name: string;
    chainNames: {
      displayName: string | null;
      languageCode: string | null;
    }[] | null;
    websites: {
      uri: string | null;
    }[] | null;
    locationCount: number | null;
  }[] | null;
}

Retorna uma lista de categorias de negócios correspondentes ao início do nome da categoria (por exemplo, 'food' corresponde a 'Food Court', mas não a 'Fast Food Restaurant').

Entradas:

- `region_code` (string, required) — The ISO 3166-1 alpha-2 country code.
- `language_code` (string, required) — The BCP 47 code of the language.
- `view` (string, required) — Specifies which parts of the Category resource to return. Values: `CATEGORY_VIEW_UNSPECIFIED` (equivalent to `BASIC`), `BASIC` (only `displayName`, `category_id`, `languageCode`), `FULL` (all fields).
- `filter_` (string, optional) — Filter string from the user; the only supported field is `displayName`, e.g. `filter=displayName=foo`.
- `page_size` (integer, optional) — How many categories to fetch per page. Default is 100, minimum is 1, maximum is 100.
- `page_token` (string, optional) — If specified, fetches the next page of categories.

Esquema de saída data:

{
  categories: {
    name: string | null;
    displayName: string | null;
    languageCode: string | null;
  }[] | null;
  nextPageToken: string | null;
}

Retorna uma lista de categorias de negócios para o idioma e os IDs de categoria (GConcept) fornecidos.

Entradas:

- `names` (array<string>, required) — The GConcept ids the localized category names should be returned for. Repeat this parameter to request more than one category; at least one name must be set.
- `language_code` (string, required) — The BCP 47 code of the language that the category names should be returned in.
- `view` (string, required) — Specifies which parts of the Category resource to return. Values: `CATEGORY_VIEW_UNSPECIFIED` (equivalent to `BASIC`), `BASIC` (only `displayName`, `category_id`, `languageCode`), `FULL` (all fields).
- `region_code` (string, optional) — The ISO 3166-1 alpha-2 country code used to infer non-standard language.

Esquema de saída data:

{
  categories: {
    name: string | null;
    displayName: string | null;
    languageCode: string | null;
  }[] | null;
}

Retorna a lista de atributos que estariam disponíveis para um local com a categoria principal e o país fornecidos. Forneça exatamente um de: parent (o nome do recurso de um local existente), OU category_name juntamente com region_code e language_code. Defina show_all como true para obter metadados de todos os atributos disponíveis, independentemente de parent/category_name — nesse caso, region_code e language_code são obrigatórios. Use page_token de uma resposta anterior para paginar pelos resultados.

Entradas:

- `parent` (string, optional) — Resource name of the location to look up available attributes for. If set, category_name, region_code, language_code and show_all are not required and must not be set.
- `category_name` (string, optional) — The primary category stable ID to find available attributes. Must be of the format categories/{category_id}.
- `region_code` (string, optional) — The ISO 3166-1 alpha-2 country code to find available attributes.
- `language_code` (string, optional) — The BCP 47 code of language to get attribute display names in. Falls back to English if unavailable.
- `show_all` (boolean, optional) — If true, metadata for all available attributes is returned, disregarding parent and category_name. region_code and language_code are required when this is true.
- `page_size` (integer, optional) — How many attributes to include per page. Default is 200, minimum is 1.
- `page_token` (string, optional) — If specified, the next page of attribute metadata is retrieved.

Esquema de saída data:

{
  attributeMetadata: {
    parent: string | null;
    valueType: string | null;
    displayName: string | null;
    groupDisplayName: string | null;
    repeatable: boolean | null;
    valueMetadata: any[] | null;
    deprecated: boolean | null;
  }[] | null;
  nextPageToken: string | null;
}

Pesquisa todos os locais possíveis no Google que correspondem à solicitação especificada e retorna as entradas GoogleLocation correspondentes. Exatamente um de location ou query deve ser fornecido.

Entradas:

- `page_size` (integer, optional) — The number of matches to return. Default is 3, maximum is 10. No pagination.
- `location` (object, optional) — Union field `search_query` — exactly one of `location` or `query` is required. Location to search for; if provided, finds locations matching the provided details.
- `query` (string, optional) — Union field `search_query` — exactly one of `location` or `query` is required. Text query to search for. Less accurate than an exact location, but can surface more inexact matches.

Esquema de saída data:

{
  googleLocations: {
    name: string | null;
    location: object | null;
    requestAdminRightsUri: string | null;
  }[] | null;
}

Retorna os valores para cada data em um determinado intervalo de tempo para uma única métrica diária especificada. Apenas dados diários estão disponíveis; métricas horárias não são suportadas.

Entradas:

- `name` (string, required) — The location for which the time series should be fetched. Format: `locations/{locationId}` where `locationId` is an unobfuscated listing id.
- `daily_metric` (string, required) — The metric to retrieve time series for. One of: `DAILY_METRIC_UNKNOWN`, `BUSINESS_IMPRESSIONS_DESKTOP_MAPS`, `BUSINESS_IMPRESSIONS_DESKTOP_SEARCH`, `BUSINESS_IMPRESSIONS_MOBILE_MAPS`, `BUSINESS_IMPRESSIONS_MOBILE_SEARCH`, `BUSINESS_CONVERSATIONS`, `BUSINESS_DIRECTION_REQUESTS`, `CALL_CLICKS`, `WEBSITE_CLICKS`, `BUSINESS_BOOKINGS`, `BUSINESS_FOOD_ORDERS`, `BUSINESS_FOOD_MENU_CLICKS`.
- `daily_range` (object, required) — The timerange to fetch. `{ "startDate": {"year", "month", "day"}, "endDate": {"year", "month", "day"} }`, both inclusive.
- `daily_sub_entity_type` (object, optional) — The sub-entity type/id the time series relates to. Currently no `DailyMetric` supports this (breakdown not available). Union of `dayOfWeek` (enum) or `timeOfDay` (`{"hours", "minutes", "seconds", "nanos"}`).

Esquema de saída data:

{
  timeSeries: {
    datedValues: {
      date: object | null;
      value: string | null;
    }[] | null;
  } | null;
}

Retorna os valores para cada data em um determinado intervalo de tempo para várias métricas diárias especificadas de uma vez. Apenas dados diários estão disponíveis; métricas horárias não são suportadas.

Entradas:

- `location` (string, required) — The location for which the time series should be fetched. Format: `locations/{locationId}` where `locationId` is an unobfuscated listing id.
- `daily_metrics` (array<string>, required) — The metrics to retrieve time series for. Same enum values as `get_daily_metrics_time_series`. Repeat this parameter for multiple metrics.
- `daily_range` (object, required) — The timerange to fetch. `{ "startDate": {"year", "month", "day"}, "endDate": {"year", "month", "day"} }`, both inclusive.

Esquema de saída data:

{
  multiDailyMetricTimeSeries: {
    dailyMetricTimeSeries: {
      dailyMetric: string | null;
      dailySubEntityType: object | null;
      timeSeries: {
        datedValues: {
          date: object | null;
          value: string | null;
        }[] | null;
      } | null;
    }[] | null;
  }[] | null;
}

Retorna as palavras-chave de pesquisa usadas para encontrar uma empresa na Pesquisa ou no Maps, cada uma acompanhada de contagens de impressões agregadas mensalmente.

Entradas:

- `parent` (string, required) — The location for which the time series should be fetched. Format: `locations/{locationId}` where `locationId` is an unobfuscated listing id.
- `monthly_range` (object, required) — The range in months to aggregate search keyword impressions over. `{ "startMonth": {"year", "month", "day"}, "endMonth": {"year", "month", "day"} }`, both inclusive — only year and month are considered.
- `page_size` (integer, optional, default: 100) — Number of results requested. Default 100, maximum 100.
- `page_token` (string, optional) — Base64-encoded token indicating the next paginated result to return.

Esquema de saída data:

{
  searchKeywordsCounts: {
    searchKeyword: string | null;
    insightsValue: {
      value: string | null;
      threshold: string | null;
    } | null;
  }[] | null;
  nextPageToken: string | null;
}

Cada ferramenta retorna o mesmo envelope de nível superior. Apenas data varia por ferramenta.

// Success
{
  "success": true,
  "statusCode": 200,
  "retriable": false,
  "retry_after_seconds": null,
  "error": null,
  "data": { ... }
}

// Error
{
  "success": false,
  "statusCode": 400,
  "retriable": false,
  "retry_after_seconds": null,
  "error": { "code": "VALIDATION_ERROR", "message": "page_size must be between 1 and 100", "details": null },
  "data": null
}

• retriable — true quando é seguro tentar novamente (limite de taxa, erro de rede, 503). false para erros de validação e autenticação.
• retry_after_seconds — segundos para aguardar antes de tentar novamente; presente apenas quando retriable é true e o upstream especifica um atraso.
• error.code — string legível por máquina: VALIDATION_ERROR (entrada inválida, capturada antes da chamada ser feita), AUTH_ERROR (sem token de acesso OAuth na credencial), UPSTREAM_ERROR (a API do Google retornou um status de erro), SERVER_ERROR (falha inesperada).

• page_size — Número máximo de resultados a retornar por página. Cada ferramenta de listagem/pesquisa define seu próprio padrão e máximo — consulte as Entradas dessa ferramenta.
• page_token — Token de paginação opaco de uma resposta anterior de nextPageToken (ou equivalente), usado para buscar a próxima página de resultados.
• filter_ — Expressão de filtro específica da ferramenta que restringe quais registros são retornados; os campos suportados diferem por ferramenta (consulte list_locations e list_categories).

Local:

locations/{locationId}
Example: locations/12345678901234567890

Atributos do Local:

locations/{locationId}/attributes
Example: locations/12345678901234567890/attributes

Atributo:

attributes/{attribute}
Example: attributes/has_wifi

Chain:

chains/{chain_place_id}
Example: chains/10248

Category:

categories/{category_id}
Example: categories/gcid:coffee_shop

• Causa: Token de acesso OAuth não fornecido nos cabeçalhos da solicitação ou formato incorreto
• Solução:
  1. Verifique se os cabeçalhos Authorization: Bearer YOUR_ACCESS_TOKEN e X-Mewcp-Credential-Id: CREDENTIAL-ID estão presentes
  2. Verifique se sua credencial do Google está ativa na sua conta MewCP

• Causa: As chamadas de API excederam seus limites de solicitação
• Solução:
  1. Verifique o uso de créditos no seu painel do Curious Layer
  2. Atualize para um plano pago ou adicione créditos para limites maiores
  3. Entre em contato com o suporte para ajustes de crédito

• Causa: Nenhuma credencial do Google vinculada à sua conta
• Solução:
  1. Vá para Credenciais no seu painel MewCP
  2. Conecte sua conta do Google via OAuth
  3. Tente novamente a solicitação com o cabeçalho X-Mewcp-Credential-Id correto

• Causa: O payload JSON é inválido ou está faltando campos obrigatórios
• Solução:
  1. Valide a sintaxe JSON antes de enviar
  2. Garanta que todos os parâmetros de ferramenta obrigatórios estejam incluídos
  3. Verifique se os tipos de parâmetros correspondem aos valores esperados

• Causa: Nome de servidor incorreto no endpoint da API
• Solução:
  1. Verifique o formato do endpoint: {server-name}/mcp/{tool-name}
  2. Use o nome de servidor correto da documentação
  3. Verifique os servidores disponíveis na sua conta Curious Layer

• Causa: A chamada upstream para a API My Business Business Information ou para a API Business Profile Performance retornou um erro
• Solução:
  1. Verifique o Painel de Status do Google Cloud para interrupções
  2. Verifique se sua conta do Google é proprietária ou gerente do local comercial e se o escopo business.manage foi concedido durante o OAuth
  3. Revise a mensagem de erro para obter detalhes específicos

• Referência da API My Business Business Information — Referência completa de endpoints para locais, cadeias, categorias, atributos e Google Locations
• Referência da API Business Profile Performance — Referência completa de endpoints para métricas de desempenho e impressões de palavras-chave de pesquisa
• Documentação do FastMCP — Especificação do FastMCP
• Credenciais do FastMCP — Pacote de credenciais do FastMCP para manipulação de credenciais