QueryInbox

npx add-mcp 'https://queryinbox.com/mcp'

[

MCP

Servidor MCP hospedado para qualquer cliente que aceite uma URL. Nada para instalar.

Conectar via MCP →

](#mcp)[

Skill para agente

Para agentes que executam comandos de shell e leem um SKILL.md, com ou sem MCP.

Instalar a skill →

](#skill)[

API REST

A camada HTTP simples por baixo de ambos. Para scripts, serviços e ferramentas personalizadas.

Chamar a API →

](#rest-api)

Criar uma chave

Abra o QueryInbox, vá em Configurações → Acesso do agente e clique em Criar chave. A chave se parece com qi_AbCdEfGh.… e é exibida apenas uma vez — copie-a antes de fechar o painel. Você pode criar várias chaves (uma por laptop, uma por agente) e revogar cada uma separadamente.

MCP

O QueryInbox serve o MCP em https://queryinbox.com/mcp (HTTP Streamable, sem sessão). Uma URL e um cabeçalho são toda a configuração: nada para instalar, e as mudanças acompanham o aplicativo.

Esta página é o guia de configuração. Para saber o que o servidor expõe em cada produto do Google — os limites que você encontrará e as perguntas que valem a pena fazer — veja as páginas do Search Console e do Google Analytics.

Claude Code

claude mcp add --transport http queryinbox https://queryinbox.com/mcp \
  --header "Authorization: Bearer qi_..."

Codex

O Codex só lê o token bearer de uma variável de ambiente, então exporte a chave primeiro:

export QUERYINBOX_API_KEY=qi_...
codex mcp add queryinbox --url https://queryinbox.com/mcp \
  --bearer-token-env-var QUERYINBOX_API_KEY

Cursor

Adicione isto a ~/.cursor/mcp.json, ou .cursor/mcp.json em um projeto:

{
  "mcpServers": {
    "queryinbox": {
      "url": "https://queryinbox.com/mcp",
      "headers": { "Authorization": "Bearer qi_..." }
    }
  }
}

opencode

Adicione um servidor remoto ao opencode.json (projeto) ou ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "queryinbox": {
      "type": "remote",
      "url": "https://queryinbox.com/mcp",
      "headers": { "Authorization": "Bearer {env:QUERYINBOX_API_KEY}" }
    }
  }
}

pi

O MCP está integrado ao pi 0.99.0 e versões posteriores. O servidor fica em ~/.pi/agent/mcp.json; adicione -l para gravar .pi/mcp.json para o projeto atual:

pi mcp add queryinbox --url https://queryinbox.com/mcp \
  --header "Authorization=Bearer qi_..."

Outros clientes remotos

Qualquer cliente que aceite uma URL e cabeçalhos funciona da mesma forma — novas versões do Claude Desktop, plugins de IDE:

{
  "mcpServers": {
    "queryinbox": {
      "url": "https://queryinbox.com/mcp",
      "headers": { "Authorization": "Bearer qi_..." }
    }
  }
}

Clientes que só falam stdio

Conecte o endpoint remoto com o pacote da comunidade mcp-remote:

npx -y mcp-remote https://queryinbox.com/mcp \
  --header "Authorization: Bearer qi_..."

Ferramentas

Ferramenta	O que faz
list_resources	Lista as propriedades do Search Console e do Analytics que esta conta do QueryInbox pode ler, além do conjunto de trabalho atual do usuário. Uma chamada que cobre ambas as APIs do Google; use-a antes de escolher um site ou propriedade.
gsc_api	Executa qualquer método somente leitura do Google Search Console. Passe o nome do método nativo e os campos de solicitação nativos desse método; tudo, exceto method e site, é encaminhado ao Google sem alterações (campos POST viram o corpo JSON, campos GET viram a string de consulta). Métodos: sites.list, sites.get, sitemaps.list, sitemaps.get, searchanalytics.query, urlInspection.index.inspect. Retorna o payload bruto do Google em data. Os dados do Search Console têm atraso de 2 a 3 dias. Chame api_reference para parâmetros e observe a cota de inspeção de URL (2.000/dia por propriedade).
ga4_data	Executa qualquer método somente leitura da API de Dados do Google Analytics. Passe o nome do método nativo e o corpo de solicitação nativo desse método (dateRanges, dimensions: [{name}], metrics: [{name}], filters,...); tudo, exceto method e property, é encaminhado sem alterações. Métodos: properties.runReport, properties.batchRunReports, properties.runPivotReport, properties.batchRunPivotReports, properties.runRealtimeReport, properties.checkCompatibility, properties.getMetadata, properties.runFunnelReport (alfa), properties.getPropertyQuotasSnapshot (alfa). Retorna o payload bruto do Google em data. Use properties.getMetadata para descobrir nomes de dimensões e métricas.
ga4_admin	Executa qualquer método somente leitura da API de Administração do Google Analytics: descoberta de contas e propriedades, fluxos de dados, eventos-chave, eventos de conversão, dimensões personalizadas e métricas personalizadas. Eles explicam o que as dimensões e métricas dos relatórios significam (por exemplo, qual evento uma métrica de keyEvents conta). Passe o nome do método nativo e os campos de solicitação nativos; tudo, exceto method, property e account, é encaminhado sem alterações. Retorna o payload bruto do Google em data.
api_reference	A referência gerada para gsc_api, ga4_data e ga4_admin: todos os métodos disponíveis, seus caminhos, parâmetros, notas e cotas do Google. Chame-a antes de um método desconhecido ou quando um nome de método for rejeitado.

Skill para agente

Para qualquer agente que execute comandos de shell e leia um SKILL.md. A skill ensina ao agente as chamadas REST que o MCP encapsula, e a chave continua sendo o único segredo necessário.

Instalação

A skill é servida em /skills/queryinbox e sua referência de métodos gerada em /skills/queryinbox/reference — abra-as no navegador primeiro, se quiser, e depois instale ambas no diretório de skills do seu harness:

# pi
mkdir -p ~/.pi/agent/skills/queryinbox
curl -fsSL https://queryinbox.com/skills/queryinbox \
  -o ~/.pi/agent/skills/queryinbox/SKILL.md
curl -fsSL https://queryinbox.com/skills/queryinbox/reference \
  -o ~/.pi/agent/skills/queryinbox/reference.md

# Claude Code
mkdir -p ~/.claude/skills/queryinbox
curl -fsSL https://queryinbox.com/skills/queryinbox \
  -o ~/.claude/skills/queryinbox/SKILL.md
curl -fsSL https://queryinbox.com/skills/queryinbox/reference \
  -o ~/.claude/skills/queryinbox/reference.md

# other harnesses that read the shared skills directory
mkdir -p ~/.agents/skills/queryinbox
curl -fsSL https://queryinbox.com/skills/queryinbox \
  -o ~/.agents/skills/queryinbox/SKILL.md
curl -fsSL https://queryinbox.com/skills/queryinbox/reference \
  -o ~/.agents/skills/queryinbox/reference.md

Atualizar a skill depois é o mesmo par de curls.

Armazenamento da chave

A skill lê QUERYINBOX_API_KEY quando definida e usa um arquivo como fallback, então a chave continua funcionando entre terminais e agentes iniciados por GUI sem tocar no seu perfil de shell:

mkdir -p ~/.config/queryinbox
printf '%s\n' 'qi_...' > ~/.config/queryinbox/api-key
chmod 600 ~/.config/queryinbox/api-key

Prefere uma variável de ambiente? Torne-a persistente em vez de exportá-la por shell: macOS/zsh ~/.zshrc, Linux/bash ~/.bashrc, fish set -Ux, Windows PowerShell setx, ou as próprias configurações de ambiente do seu harness (para Claude Code, o bloco env em ~/.claude/settings.json).

API REST

O MCP é um encapsulamento desses endpoints, e a skill os documenta. Há uma rota por API do Google; method nomeia o endpoint a ser chamado e todos os outros campos são a solicitação nativa desse endpoint — campos POST viram o corpo JSON, campos GET viram a string de consulta. Envie a chave como token bearer; o seletor site ou property aceita um valor completo ou uma substring única e é resolvido antes da chamada.

curl -s https://queryinbox.com/api/agent/resources \
  -H "Authorization: Bearer $QUERYINBOX_API_KEY"

curl -s https://queryinbox.com/api/agent/gsc \
  -H "Authorization: Bearer $QUERYINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"searchanalytics.query","site":"example.com",
       "startDate":"2026-09-01","endDate":"2026-09-28",
       "dimensions":["query"],"rowLimit":20}'

curl -s https://queryinbox.com/api/agent/ga4 \
  -H "Authorization: Bearer $QUERYINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"properties.runReport","property":"example.com",
       "dateRanges":[{"startDate":"2026-09-01","endDate":"2026-09-28"}],
       "dimensions":[{"name":"date"}],
       "metrics":[{"name":"sessions"},{"name":"activeUsers"}]}'

Também disponíveis: POST /api/agent/ga4/admin para configuração e metadados de propriedades (fluxos de dados, eventos-chave, dimensões personalizadas) e POST /api/agent/reference para a lista completa de métodos com parâmetros e cotas.

Erros

HTTP	Código	Significado
400	invalid_request	O corpo está malformado ou um campo obrigatório está ausente ( method, ou o seletor que um método precisa)
400	method_not_available	O método não faz parte da superfície somente leitura (gravações, configuração de contas ou exportações que criam estado)
401	invalid_api_key	A chave está errada ou revogada — crie uma nova em Configurações
404	site_not_found, site_ambiguous, property_not_found, property_ambiguous	Os seletores não corresponderam a nada ou a vários recursos; o corpo lista os candidatos
409	reauth_required	A chave está correta, mas a autorização subjacente do Google expirou ou foi revogada. Entre novamente no QueryInbox; a resposta traz um reauthUrl, e a mesma chave continua funcionando depois
429	rate_limited	Mais de 120 solicitações em um minuto — recue
429	google_quota_exceeded	Cota própria do Google (por exemplo, a inspeção de URL de 2.000/dia por propriedade) — recue, respeitando retryAfter quando presente
502	google_error	O próprio Google falhou ou rejeitou a consulta

Bom saber

• Somente leitura. Uma chave pode ler as APIs de leitura do Search Console e do Analytics cobertas por esses dois escopos; alguns endpoints são deliberadamente excluídos (configuração de contas, exportações que criam estado). Nada é gravado de volta no Google.
• As chaves não expiram sozinhas. Revogue-as em Configurações a qualquer momento, ou use Desconectar Google para remover a autorização do Google e todas as chaves de uma vez.
• O Search Console tem atraso de 2 a 3 dias, e o dia mais recente é parcial. O Analytics relata por dia; um relatório em tempo real (properties.runRealtimeReport) cobre os últimos 30 minutos.
• O agente nunca vê sua senha ou tokens do Google — apenas esta chave. Revogar a chave corta o acesso imediatamente.