Grafana

oficial

Pesquise dashboards, investigue incidentes e consulte fontes de dados em sua instância do Grafana

GitHub

3.5k

Experimente este MCPPatrocinado

O que você pode fazer com Grafana MCP?

Pesquisar e inspecionar dashboards — Solicite dashboards por título, pasta, tag ou status de favorito e obtenha resumos, versões ou propriedades específicas de JSONPath como $.title via search_dashboards, get_dashboard_summary ou get_dashboard_property.
Consultar Prometheus e Loki — Execute consultas PromQL ou LogQL, busque metadados de métricas/rótulos e calcule percentis de histograma (p50–p99) diretamente dos seus datasources.
Gerenciar alertas e incidentes — Liste ou crie regras de alerta, verifique status de disparo e pesquise ou atualize registros de Incidentes do Grafana com campos personalizados.
Explorar dados SQL e CloudWatch — Liste tabelas, descreva esquemas e execute SQL com macros em ClickHouse, Snowflake, Athena, MySQL, PostgreSQL ou MSSQL; também consulte métricas do CloudWatch por namespace e dimensão.
Renderizar dashboards e gerar links — Obtenha um painel ou dashboard como imagem PNG ou crie deeplinks precisos para dashboards, painéis e Explore com intervalos de tempo e variáveis.

Documentação

Servidor MCP do Grafana

Um servidor Model Context Protocol (MCP) para Grafana.

Isso fornece acesso à sua instância do Grafana e ao ecossistema ao redor.

Início Rápido

Requer uv. Adicione o seguinte à configuração do seu cliente MCP (ex.: Claude Desktop, Cursor):

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Para Grafana Cloud, substitua GRAFANA_URL pela URL da sua instância (ex.: https://myinstance.grafana.net). Consulte Uso para mais opções de instalação, incluindo Docker, binário e Helm.

Requisitos

Versão do Grafana 9.0 ou posterior é necessária para funcionalidade completa. Alguns recursos, particularmente operações relacionadas a datasources, podem não funcionar corretamente com versões anteriores devido à ausência de endpoints de API.

Recursos

Os seguintes recursos estão atualmente disponíveis no servidor MCP. Esta lista é apenas para fins informativos e não representa um roteiro ou compromisso com recursos futuros.

Dashboards

Buscar dashboards: Encontre dashboards por título, UID da pasta, tag ou status de favorito
Obter dashboard por UID: Recupere detalhes completos do dashboard usando seu identificador único. Passe o version opcional para carregar um snapshot salvo em vez do dashboard atual. Aviso: Dashboards grandes podem consumir espaço significativo da janela de contexto.
Listar versões do dashboard: Liste versões salvas de um dashboard como metadados compactos (número da versão, autor, timestamp, mensagem de salvamento)
Obter resumo do dashboard: Obtenha uma visão geral compacta de um dashboard, incluindo título, contagem de painéis, tipos de painéis, variáveis e metadados, sem o JSON completo para minimizar o uso da janela de contexto
Obter propriedade do dashboard: Extraia partes específicas de um dashboard usando expressões JSONPath (ex.: $.title, $.panels[*].title) para buscar apenas os dados necessários e reduzir o consumo da janela de contexto
Atualizar ou criar um dashboard: Modifique dashboards existentes ou crie novos. Aviso: Requer o JSON completo do dashboard, o que pode consumir grandes quantidades de espaço da janela de contexto.
Aplicar patch no dashboard: Aplique alterações específicas em um dashboard sem exigir o JSON completo, reduzindo significativamente o uso da janela de contexto para modificações direcionadas
Obter consultas de painéis e informações do datasource: Obtenha o título, a string de consulta e as informações do datasource (incluindo UID e tipo, se disponível) de cada painel em um dashboard

Executar Consulta de Painel

Nota: As ferramentas de execução de consulta de painel estão desabilitadas por padrão. Para habilitá-las, adicione runpanelquery à sua flag --enabled-tools.

Executar consulta de painel: Execute a consulta de um painel do dashboard com intervalos de tempo personalizados e substituições de variáveis.

Gerenciamento da Janela de Contexto

As ferramentas de dashboard agora incluem várias estratégias para gerenciar efetivamente o uso da janela de contexto (issue #101):

Use get_dashboard_summary para visão geral do dashboard e planejamento de modificações
Use get_dashboard_property com JSONPath quando você precisar apenas de partes específicas do dashboard
Evite get_dashboard_by_uid a menos que você precise especificamente do JSON completo do dashboard

Datasources

Listar e buscar informações de datasources: Visualize todos os datasources configurados e recupere informações detalhadas sobre cada um.
- Tipos de datasources suportados: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Exemplos de Consultas

Nota: As ferramentas de exemplos de consultas estão desabilitadas por padrão. Para habilitá-las, adicione examples à sua flag --enabled-tools.

Obter exemplos de consultas: Recupere exemplos de consultas para diferentes tipos de datasources para aprender a sintaxe de consulta.

Consultas ao Prometheus

Consultar Prometheus: Execute consultas PromQL (suporta consultas de métricas instantâneas e de intervalo) contra datasources Prometheus.
Consultar metadados do Prometheus: Recupere metadados de métricas, nomes de métricas, nomes de labels e valores de labels de datasources Prometheus.
Consultar percentis de histograma: Calcule valores de percentis de histograma (p50, p90, p95, p99) usando histogram_quantile.

Consultas ao Loki

Consultar logs e métricas do Loki: Execute consultas de logs e consultas de métricas usando LogQL contra datasources Loki.
Consultar metadados do Loki: Recupere nomes de labels, valores de labels e estatísticas de streams de datasources Loki.
Consultar padrões do Loki: Recupere padrões de logs detectados pelo Loki para identificar estruturas de log comuns e anomalias.

Consultas ao InfluxDB

Nota: As ferramentas do InfluxDB estão desabilitadas por padrão. Para habilitá-las, adicione influxdb à sua flag --enabled-tools.

Consultar InfluxDB: Execute consultas contra datasources InfluxDB usando InfluxQL (v1.x) ou Flux (v2.x). O dialeto é inferido da configuração do datasource, ou pode ser definido explicitamente via o parâmetro dialect.

Consultas a Datasources SQL

Nota: As ferramentas SQL estão desabilitadas por padrão. Para habilitá-las, adicione sql à sua flag --enabled-tools. Os aliases de compatibilidade clickhouse, snowflake e athena também funcionam.

As ferramentas SQL unificadas suportam ClickHouse, Snowflake, Athena, MySQL, PostgreSQL e MSSQL por meio de um único conjunto de ferramentas. As consultas passam pelos plugins de datasource do Grafana, portanto a autenticação é tratada pela configuração do datasource — as credenciais nunca são vistas pelo servidor MCP.

Listar bancos de dados/esquemas/catálogos: Descubra unidades organizacionais para um datasource SQL. Para Athena, omita o catálogo para listar catálogos, ou passe um catálogo para listar bancos de dados.
Listar tabelas: Liste tabelas em um banco de dados ou esquema com metadados (contagens de linhas, tamanhos quando disponíveis).
Descrever esquema de tabela: Obtenha nomes de colunas, tipos, nulidade, padrões e comentários.
Consultar SQL: Execute consultas SQL com substituição de macros específicas do datasource ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), aplicação automática de limites e suporte a variáveis de template.

Consultas ao CloudWatch

Nota: As ferramentas do CloudWatch estão desabilitadas por padrão. Para habilitá-las, adicione cloudwatch à sua flag --enabled-tools.

Listar namespaces do CloudWatch: Descubra namespaces disponíveis do AWS CloudWatch.
Listar métricas do CloudWatch: Liste métricas disponíveis em um namespace específico.
Listar dimensões do CloudWatch: Obtenha dimensões para filtrar consultas de métricas.
Consultar CloudWatch: Execute consultas de métricas do CloudWatch com suporte a intervalo de tempo.

Consultas ao Google Cloud Logging

Nota: As ferramentas do Google Cloud Logging estão desabilitadas por padrão. Para habilitá-las, adicione cloudlogging à sua flag --enabled-tools. Requer o plugin de datasource do Google Cloud Logging (googlecloud-logging-datasource) versão 1.8.0 ou posterior, que precisa do Grafana 11.2+. Versões mais antigas do plugin retornam um layout de resposta diferente e query_cloud_logging relata um erro solicitando uma atualização.

Listar projetos do Cloud Logging: Descubra os IDs de projetos GCP dos quais o datasource pode ler logs.
Listar buckets e visualizações do Cloud Logging: Descubra buckets de logs e visualizações de logs para escopar uma consulta.
Consultar Cloud Logging: Execute filtros da linguagem de consulta do Cloud Logging (ex.: resource.type="k8s_container" AND severity>=ERROR) com intervalo de tempo e limite; retorna entradas do mais recente para o mais antigo com severidade, corpo, labels e ID de rastreamento. A autenticação GCP é tratada pela configuração do datasource.

Consultas ao Graphite

Nota: As ferramentas do Graphite estão desabilitadas por padrão. Para habilitá-las, adicione graphite à sua flag --enabled-tools.

Consultar Graphite: Execute consultas da API de renderização do Graphite contra um datasource Graphite.
Listar métricas do Graphite: Navegue e descubra caminhos de métricas do Graphite.
Listar tags do Graphite: Liste tags e valores de tags disponíveis do Graphite.
Consultar densidade do Graphite: Consulte a densidade de métricas do Graphite para um padrão específico.

Consultas ao Elasticsearch/OpenSearch

Nota: As ferramentas do Elasticsearch/OpenSearch estão desabilitadas por padrão. Para habilitá-las, adicione elasticsearch à sua flag --enabled-tools.

Consultar Elasticsearch/OpenSearch: Execute consultas de busca contra datasources Elasticsearch ou OpenSearch usando sintaxe de consulta Lucene ou Elasticsearch Query DSL. Suporta filtragem por intervalo de tempo e recuperação de logs, métricas ou qualquer dado indexado. Retorna documentos com seu índice, ID, campos de origem e pontuação de relevância opcional.

Consultas ao Quickwit

Nota: As ferramentas do Quickwit estão desabilitadas por padrão. Para habilitá-las, adicione quickwit à sua flag --enabled-tools.

Consultar Quickwit: Execute consultas de busca contra datasources Quickwit usando sintaxe de consulta Lucene ou Query DSL parcial compatível com Elasticsearch. Suporta filtragem por intervalo de tempo e recuperação de logs ou outros documentos indexados. Retorna documentos com seu índice, ID, campos de origem e pontuação de relevância opcional.

Observabilidade de Agentes

Nota: As ferramentas de Observabilidade de Agentes estão desabilitadas por padrão e funcionam apenas no Grafana Cloud. Para habilitá-las, adicione agento11y à sua flag --enabled-tools.

Listar e pesquisar conversas: Liste conversas recentes de LLM ou pesquise-as com uma expressão de filtro (modelo, provedor, agente, status, tipo de erro, resultados de avaliação e mais) em um intervalo de tempo. Os resultados da pesquisa incluem contagens de erros, resumos de classificações, resumos de avaliações e IDs de rastreamento.
Obter detalhes da conversa: Busque uma única conversa com todas as suas gerações, incluindo prompts e saídas.
Obter detalhes e pontuações da geração: Busque uma única geração por ID e suas pontuações de avaliação (avaliador, chave de pontuação, valor, aprovado, explicação).
Ler o catálogo de agentes: Liste os agentes que enviam telemetria, busque uma versão completa de um agente (prompt de sistema completo, cada ferramenta com seu esquema JSON e os modelos em que foi executado), percorra o histórico de versões de um agente e compare os agregados de pontuação de avaliação por versão. Versões efetivas são hashes sha256: que uma alteração de ferramenta nunca afeta; para um agente que não relata versão própria, eles fazem hash do prompt de sistema, então uma edição de prompt gera uma nova versão. As linhas de catálogo e versão carregam um token_estimate, que vale a pena verificar antes de buscar um prompt completo.
Inspecionar avaliadores e modelos: Leia os avaliadores de onde uma pontuação veio, os modelos dos quais foram derivados e os provedores e modelos de juiz disponíveis para avaliadores de LLM. Com ferramentas de escrita habilitadas, também crie, bifurque, teste e exclua avaliadores.
Inspecionar regras de avaliação e guardas: Leia as regras de avaliação assíncronas que vinculam avaliadores ao tráfego de produção e as guardas (regras de hook) que são executadas inline e podem avisar ou negar. Com ferramentas de escrita habilitadas, também crie, atualize, visualize e exclua-as. Escritas e as operações não persistentes preview_rule e test_evaluator precisam da permissão grafana-agento11y-app.eval:write, concedida pela função Admin do Agento11y.
Selecionar conversas e coleções salvas: Leia as conversas salvas (marcadores que dão a uma conversa um ID estável, nome e tags) e as coleções que as agrupam, incluindo a contagem de membros de cada coleção e as coleções incorporadas em cada linha de conversa salva. Com ferramentas de escrita habilitadas, também marque uma conversa, crie e edite coleções e adicione ou remova membros. Essas escritas precisam da mesma permissão grafana-agento11y-app.eval:write.
Ler e editar suítes de teste: Liste as suítes de teste versionadas contra as quais experimentos offline são executados, leia uma com seu histórico completo de versões e percorra os casos de teste de uma versão. Com ferramentas de escrita habilitadas, também crie uma suíte, renomeie ou re-tagueie-a, abra uma versão de rascunho, publique-a e escreva ou exclua seus casos de teste. Uma versão publicada é congelada, então uma edição significa abrir um novo rascunho. Essas escritas precisam de grafana-agento11y-app.eval:write.
Ler experimentos offline: Liste as execuções de avaliação sobre uma suíte de teste e leia uma com sua taxa de aprovação principal, custo e totais de tokens. Aprofunde-se em um relatório por caso de teste para tentativas, suas pontuações com a explicação de cada juiz e seus metadados de artefato. Com ferramentas de escrita habilitadas, também renomeie ou re-tagueie um experimento e cancele um em execução, o que precisa de grafana-agento11y-app.eval:write. Experimentos são criados por executores SDK, não por esta ferramenta.

Assistente Grafana

Nota: As ferramentas do Assistente estão desabilitadas por padrão e exigem o plugin Grafana Assistant (grafana-assistant-app) instalado na instância Grafana de destino. Elas também são ferramentas de escrita (o assistente pode alterar o estado da pilha), então são ignoradas quando --disable-write está definido. Para habilitá-las, adicione assistant ao seu sinalizador --enabled-tools.

Perguntar ao assistente: Envie um prompt em linguagem natural para o Grafana Assistant e aguarde a resposta completa em texto. O assistente pode usar ferramentas, métricas, logs e outro contexto da pilha—mais amplo do que disparar uma única consulta de fonte de dados isolada. Passe o contextId retornado de volta em uma chamada de acompanhamento para continuar a mesma conversa. Tarefas complexas podem levar vários minutos; a chamada bloqueia até que a resposta termine ou a solicitação expire (5 minutos).

Incidentes

Pesquisar, criar e atualizar incidentes: Gerencie incidentes no Grafana Incident, incluindo pesquisa, criação, adição de atividades e leitura ou definição de campos personalizados.

Investigações Sift

Listar investigações Sift: Recupere uma lista de investigações Sift, com suporte para um parâmetro de limite.
Obter investigação Sift: Recupere detalhes de uma investigação Sift específica pelo seu UUID.
Obter análises Sift: Recupere uma análise específica de uma investigação Sift.
Encontrar padrões de erro em logs: Detecte padrões de erro elevados em logs Loki usando Sift.
Encontrar solicitações lentas: Detecte solicitações lentas usando Sift (Tempo).

Alertas

Listar e buscar informações de regras de alerta: Veja regras de alerta e seus status (disparando/normal/erro/etc.) no Grafana. Suporta regras gerenciadas pelo Grafana e regras gerenciadas por fontes de dados do Prometheus ou Loki.
Criar e atualizar regras de alerta: Crie novas regras de alerta ou modifique as existentes.
Excluir regras de alerta: Remova regras de alerta por UID.
Gerenciar roteamento de alertas: Veja políticas de notificação, pontos de contato e intervalos de tempo. Suporta pontos de contato gerenciados pelo Grafana e receptores de fontes de dados Alertmanager externas (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

Listar e gerenciar escalas: Veja e gerencie escalas de plantão no Grafana OnCall.
Obter detalhes de turnos: Recupere informações detalhadas sobre turnos de plantão específicos.
Obter usuários de plantão atuais: Veja quais usuários estão atualmente de plantão para uma escala.
Listar equipes e usuários: Veja todas as equipes e usuários do OnCall.
Listar grupos de alerta: Veja e filtre grupos de alerta do Grafana OnCall por vários critérios, incluindo estado, integração, rótulos e intervalo de tempo.
Obter detalhes do grupo de alerta: Recupere informações detalhadas sobre um grupo de alerta específico pelo seu ID.

Administração

Nota: As ferramentas de Administração estão desabilitadas por padrão. Para habilitá-las, inclua admin no seu sinalizador --enabled-tools.

Listar equipes: Veja todas as equipes configuradas no Grafana.
Listar usuários: Veja todos os usuários em uma organização no Grafana.
Listar todas as funções: Liste todas as funções do Grafana, com um filtro opcional para funções delegáveis.
Obter detalhes da função: Obtenha detalhes para uma função específica do Grafana por UID.
Listar atribuições para uma função: Liste todos os usuários, equipes e contas de serviço atribuídos a uma função.
Listar funções para usuários: Liste todas as funções atribuídas a um ou mais usuários.
Listar funções para equipes: Liste todas as funções atribuídas a uma ou mais equipes.
Listar permissões para um recurso: Liste todas as permissões definidas para um recurso específico (painel, fonte de dados, pasta, etc.).
Descrever um recurso Grafana: Liste permissões disponíveis e capacidades de atribuição para um tipo de recurso.

Usuário

Informações do usuário: Obtenha a identidade atual do Grafana — login, e-mail, nome, se é um administrador do Grafana (servidor), a organização atual e as organizações que a credencial pode acessar (com funções). Use para descobrir valores válidos de orgId para solicitações multi-organização.

Navegação

Gerar deeplinks: Crie URLs de deeplink precisas para recursos do Grafana em vez de depender de adivinhação de URL por LLM.
- Links de painéis: Gere links diretos para painéis usando seu UID (por exemplo, http://localhost:3000/d/dashboard-uid)
- Links de painéis individuais: Crie links para painéis específicos dentro de painéis com o parâmetro viewPanel (por exemplo, http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Links do Explore: Gere links para o Grafana Explore com fontes de dados pré-configuradas (por exemplo, http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana abaixo de 10.2 não entende panes, então o formato legado ?left={...} é emitido para essas versões.
- Suporte a intervalo de tempo: Adicione parâmetros de intervalo de tempo aos links (from=now-1h&to=now)
- Parâmetros personalizados: Inclua parâmetros de consulta adicionais, como variáveis de painel ou intervalos de atualização

Anotações

Obter anotações: Consulte anotações com filtros. Suporta intervalo de tempo, UID do painel, tags e modo de correspondência.
Criar anotação: Crie uma nova anotação em um painel ou painel individual.
Criar anotação Graphite: Crie anotações usando o formato Graphite (what, when, tags, data).
Atualizar anotação: Substitua todos os campos de uma anotação existente (atualização completa).
Corrigir anotação: Atualize apenas campos específicos de uma anotação (atualização parcial).
Excluir anotação: Exclua permanentemente uma anotação por ID.
Obter tags de anotação: Liste tags de anotação disponíveis com filtragem opcional.

Snapshots

Listar snapshots: Liste snapshots de painéis com filtros opcionais de consulta e limite.
Obter snapshot: Recupere metadados de snapshot e payload do painel pela chave do snapshot.
Criar snapshot: Crie um snapshot de painel a partir de um payload completo do painel, com opções opcionais de expiração e snapshot externo.
Excluir snapshot: Exclua um snapshot pela chave do snapshot.

Renderização

Obter imagem de painel ou painel individual: Renderize um painel do Grafana ou um painel completo como uma imagem PNG. Retorna a imagem como dados codificados em base64 para uso em relatórios, alertas ou apresentações. Suporta personalização de dimensões, intervalo de tempo, tema, escala e variáveis do painel. Também suporta renderização de painéis ainda não aplicados de um branch de repositório de provisionamento (por exemplo, uma prévia de PR git-sync) via o parâmetro opcional provisioningPreview.
- Nota: Requer o serviço Grafana Image Renderer instalado e configurado.

Provisionamento

Listar repositórios de provisionamento: Liste repositórios de provisionamento configurados para esta instância Grafana (por exemplo, fontes git-sync), retornando o slug de cada repositório junto com sua URL de origem, branch, caminho, estado de sincronização e saúde.
Validar arquivo de provisionamento: Aplique em modo de simulação um arquivo de um repositório de provisionamento em um branch ou commit específico. Retorna se seria aceito, a ação do recurso (criar/atualizar), o tipo de recurso de destino e quaisquer erros de validação estruturados — a mesma superfície de admissão que o comentarista de PR do Grafana usa.

A lista de ferramentas é configurável, então você pode escolher quais ferramentas deseja disponibilizar ao cliente MCP. Isso é útil se você não usa certa funcionalidade ou se não quer ocupar muito da janela de contexto. Para desabilitar uma categoria de ferramentas, use o sinalizador --disable-<category> ao iniciar o servidor. Por exemplo, para desabilitar as ferramentas OnCall, use --disable-oncall, ou para desabilitar a geração de deeplinks de navegação, use --disable-navigation.

Permissões RBAC

Cada ferramenta requer permissões RBAC específicas para funcionar corretamente. Ao criar uma conta de serviço para o servidor MCP, garanta que ela tenha as permissões necessárias com base nas ferramentas que você planeja usar. As permissões listadas são as ações mínimas necessárias — você também pode precisar de escopos apropriados (por exemplo, datasources:*, dashboards:*, folders:*) dependendo do seu caso de uso.

Dica: Se você não está familiarizado com RBAC do Grafana ou quer uma configuração mais rápida e simples em vez de configurar muitos escopos granulares, você pode atribuir uma função integrada como Editor à conta de serviço. A função Editor concede acesso amplo de leitura/escrita que permitirá a maioria das operações do servidor MCP; ela é menos granular (e portanto menos restritiva) do que escopos aplicados manualmente, então use-a apenas quando a conveniência for mais importante do que acesso estrito de privilégio mínimo.

Nota: As ferramentas Grafana Incident e Sift usam funções básicas do Grafana em vez de permissões RBAC refinadas:

Função Viewer: Necessária para operações somente leitura (listar incidentes, obter investigações)
Função Editor: Necessária para operações de escrita (criar incidentes, modificar investigações)

Para mais informações sobre RBAC do Grafana, veja a documentação oficial.

Escopos RBAC

Escopos definem os recursos específicos aos quais as permissões se aplicam. Cada ação requer tanto a permissão apropriada quanto a combinação de escopo.

Padrões Comuns de Escopo:

Acesso amplo: Use curingas * para acesso em toda a organização
- datasources:* - Acesso a todas as fontes de dados
- dashboards:* - Acesso a todos os dashboards
- folders:* - Acesso a todas as pastas
- teams:* - Acesso a todas as equipes
Acesso limitado: Use UIDs ou IDs específicos para restringir o acesso a recursos individuais
- datasources:uid:prometheus-uid - Acesso apenas a uma fonte de dados Prometheus específica
- dashboards:uid:abc123 - Acesso apenas ao dashboard com UID abc123
- folders:uid:xyz789 - Acesso apenas à pasta com UID xyz789
- teams:id:5 - Acesso apenas à equipe com ID 5
- global.users:id:123 - Acesso apenas ao usuário com ID 123

Exemplos:

Acesso completo ao servidor MCP: Conceda permissões amplas para todas as ferramentas

datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

Acesso limitado a fontes de dados: Consulte apenas instâncias específicas do Prometheus e Loki

datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

Acesso específico a dashboards: Leia apenas dashboards específicos

dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

Ferramentas

Ferramenta	Categoria	Descrição	Permissões RBAC Necessárias	Escopos Necessários
`list_teams`	Administração	Listar todas as equipes	`teams:read`	`teams:*` ou `teams:id:1`
`list_users_by_org`	Administração	Listar todos os usuários em uma organização	`users:read`	`global.users:*` ou `global.users:id:123`
`list_all_roles`	Administração	Listar todas as funções do Grafana	`roles:read`	`roles:*`
`get_role_details`	Administração	Obter detalhes de uma função do Grafana	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Administração	Listar atribuições para uma função	`roles:read`	`roles:uid:editor`
`list_user_roles`	Administração	Listar funções para usuários	`roles:read`	`global.users:id:123`
`list_team_roles`	Administração	Listar funções para equipes	`roles:read`	`teams:id:7`
`get_resource_permissions`	Administração	Listar permissões para um recurso	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Administração	Descrever um tipo de recurso do Grafana	`permissions:read`	`dashboards:*`
`user_info`	Usuário	Identidade atual, capacidades e organizações acessíveis	Nenhuma (usuário autenticado)	—
`search_dashboards`	Pesquisa	Pesquisar painéis por consulta, UID de pasta, tag ou favoritos	`dashboards:read`	`dashboards:*` ou `dashboards:uid:abc123`
`get_dashboard_by_uid`	Painel	Obter um painel por uid, opcionalmente uma versão salva	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Painel	Listar versões salvas de um painel (versão, autor, hora, mensagem)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Painel	Atualizar ou criar um novo painel	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` ou `folders:uid:xyz789`
`get_dashboard_panel_queries`	Painel	Obter título do painel, consultas, UID e tipo da fonte de dados de um painel	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	ExecutarConsultaDoPainel*	Executar uma ou mais consultas de painel	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Painel	Extrair partes específicas de um painel usando expressões JSONPath	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Painel	Obter um resumo compacto de um painel sem o JSON completo	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Fontes de dados	Listar fontes de dados	`datasources:read`	`datasources:*`
`get_datasource`	Fontes de dados	Obter uma fonte de dados por UID ou nome	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Exemplos*	Obter consultas de exemplo para um tipo de fonte de dados	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Executar uma consulta contra uma fonte de dados Prometheus	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Listar metadados de métricas	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Listar nomes de métricas disponíveis	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Listar nomes de rótulos que correspondem a um seletor	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Listar valores para um rótulo específico	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Calcular valores de percentil de histograma	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Incidente	Listar incidentes no Grafana Incident, opcionalmente com seus valores de campos personalizados	Função de visualizador	N/A
`create_incident`	Incidente	Criar um incidente no Grafana Incident, opcionalmente definindo campos personalizados	Função de editor	N/A
`add_activity_to_incident`	Incidente	Adicionar um item de atividade a um incidente no Grafana Incident	Função de editor	N/A
`update_incident`	Incidente	Atualizar um incidente no Grafana Incident (status, gravidade, título ou campos personalizados)	Função de editor	N/A
`get_incident`	Incidente	Obter um único incidente por ID, incluindo seus campos personalizados	Função de visualizador	N/A
`list_incident_custom_fields`	Incidente	Listar os campos personalizados configurados para incidentes, com seus tipos e opções de seleção	Função de visualizador	N/A
`query_loki_logs`	Loki	Consultar e recuperar logs usando LogQL (consultas de log ou métricas)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Listar todos os nomes de rótulos disponíveis nos logs	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Listar valores para um rótulo de log específico	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Obter estatísticas sobre fluxos de logs	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Consultar padrões de log detectados para identificar estruturas comuns	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Auditar uma estratégia de rótulos do Loki (ativa ou estática) e opcionalmente diagnosticar o desempenho de consultas	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Configuração	Gerar um trecho de código Alloy `loki.process` impondo rótulos aprovados	N/A	N/A
`query_influxdb`	InfluxDB	Consultar InfluxDB usando InfluxQL (v1) ou Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Listar bancos de dados, esquemas ou catálogos de uma fonte de dados SQL	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Listar tabelas em uma fonte de dados SQL	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Obter o esquema de colunas de uma tabela	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Executar consultas SQL com substituição de macros	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Listar namespaces disponíveis do AWS CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Listar métricas em um namespace	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Listar dimensões de uma métrica	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Listar valores para uma chave de dimensão	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Executar consultas de métricas do CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	Listar projetos GCP legíveis por uma fonte de dados do Google Cloud Logging	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Listar buckets de logs em um projeto GCP	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Listar visualizações de logs em um bucket de logs	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Consultar logs com a linguagem de consulta do Cloud Logging	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Consultar Elasticsearch ou OpenSearch usando sintaxe Lucene ou Query DSL	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Consultar Quickwit usando sintaxe Lucene ou Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_manage_rules`	Alerting	Gerenciar regras de alerta (listar, obter, versões, criar, atualizar, excluir)	`alert.rules:read` + `alert.rules:write` para mutações	`folders:*` ou `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Gerenciar políticas de notificação, pontos de contato e intervalos de tempo	`alert.notifications:read`	Escopo global
`alerting_manage_silences`	Alerting	Gerenciar silêncios de alerta (listar, obter, criar, atualizar, expirar)	`alert.instances:read` + `alert.instances:write` para mutações	Escopo global
`list_oncall_schedules`	OnCall	Listar escalas do Grafana OnCall	`grafana-oncall-app.schedules:read`	Escopos específicos de plugin
`get_oncall_shift`	OnCall	Obter detalhes de um turno específico do OnCall	`grafana-oncall-app.schedules:read`	Escopos específicos de plugin
`get_current_oncall_users`	OnCall	Obter usuários atualmente em plantão para uma escala específica	`grafana-oncall-app.schedules:read`	Escopos específicos de plugin
`list_oncall_teams`	OnCall	Listar equipes do Grafana OnCall	`grafana-oncall-app.user-settings:read`	Escopos específicos de plugin
`list_oncall_users`	OnCall	Listar usuários do Grafana OnCall	`grafana-oncall-app.user-settings:read`	Escopos específicos de plugin
`list_alert_groups`	OnCall	Listar grupos de alerta do Grafana OnCall com opções de filtro	`grafana-oncall-app.alert-groups:read`	Escopos específicos de plugin
`get_alert_group`	OnCall	Obter um grupo de alerta específico do Grafana OnCall pelo seu ID	`grafana-oncall-app.alert-groups:read`	Escopos específicos de plugin
`update_alert_group`	OnCall	Reconhecer, não reconhecer, resolver ou não resolver um grupo de alerta	`grafana-oncall-app.alert-groups:write` (e `:read`)	Escopos específicos de plugin
`get_sift_investigation`	Sift	Recuperar uma investigação Sift existente pelo seu UUID	Função de visualizador	N/A
`get_sift_analysis`	Sift	Recuperar uma análise específica de uma investigação Sift	Função de visualizador	N/A
`list_sift_investigations`	Sift	Recuperar uma lista de investigações Sift com um limite opcional	Função de visualizador	N/A
`find_error_pattern_logs`	Sift	Encontra padrões de erro elevados em logs do Loki.	Função de editor	N/A
`find_slow_requests`	Sift	Encontra solicitações lentas nas fontes de dados tempo relevantes.	Função de editor	N/A
`list_pyroscope_label_names`	Pyroscope	Listar nomes de rótulos que correspondem a um seletor	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Listar valores de rótulos que correspondem a um seletor para um nome de rótulo	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Listar tipos de perfil disponíveis	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Consultar perfis, métricas ou ambos do Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Obter resumo de asserções para uma determinada entidade	Permissões específicas de plugin	Escopos específicos de plugin
`agento11y_manage_conversations`	Agent Observability*	Listar, pesquisar e buscar conversas de LLM do Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Buscar detalhes de geração de LLM e pontuações de avaliação do Grafana Agent Observability	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Ler o catálogo de agentes: listar agentes, obter uma versão de agente completa, listar histórico de versões e agregados de pontuação por versão	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Gerenciar avaliadores, modelos de avaliadores e o catálogo de juízes (listar, obter, upsert, bifurcar, testar, excluir)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutações e testes	N/A
`agento11y_manage_eval_rules`	Agent Observability*	Gerenciar regras de avaliação e proteções (listar, obter, criar, atualizar, visualizar, excluir)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutações e visualizações	N/A
`agento11y_manage_eval_collections`	Agent Observability*	Gerenciar conversas salvas e as coleções que as agrupam (listar, obter, salvar, criar, atualizar, excluir, adicionar e remover membros)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutações	N/A
`agento11y_manage_experiments`	Observabilidade de Agentes*	Ler experimentos offline, seus testes, pontuações, metadados de artefatos e facetas de filtro; atualizar e cancelar um experimento	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutações	N/A
`agento11y_manage_test_suites`	Observabilidade de Agentes*	Gerenciar as suítes de teste contra as quais os experimentos offline são executados, suas versões e seus casos de teste (listar, obter, criar, atualizar, rascunhar, publicar, upsert, excluir)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutações	N/A
`ask_assistant`	Assistente*	Enviar um prompt ao Grafana Assistant e retornar a resposta completa em texto (multiturno via `contextId`)	Permissões específicas do plugin	Escopos específicos do plugin
`generate_deeplink`	Navegação	Gerar URLs de deeplink precisas para recursos do Grafana	Nenhuma (geração de URL somente leitura)	N/A
`get_annotations`	Anotações	Buscar anotações com filtros	`annotations:read`	`annotations:*` ou `annotations:id:123`
`create_annotation`	Anotações	Criar uma nova anotação (formato padrão ou Graphite)	`annotations:write`	`annotations:*`
`update_annotation`	Anotações	Atualizar campos específicos de uma anotação (atualização parcial)	`annotations:write`	`annotations:*`
`delete_annotation`	Anotações	Excluir uma anotação por ID	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Anotações	Listar tags de anotações com filtragem opcional	`annotations:read`	`annotations:*`
`list_snapshots`	Snapshot	Listar snapshots de dashboard com consulta opcional e filtros de limite	`dashboards:read`	`dashboards:*` ou `dashboards:uid:abc123`
`get_snapshot`	Snapshot	Obter metadados do snapshot e payload do dashboard pela chave do snapshot	`dashboards:read`	`dashboards:*` ou `dashboards:uid:abc123`
`create_snapshot`	Snapshot	Criar um snapshot de dashboard a partir de um payload completo do dashboard	`dashboards:write`	`dashboards:*` ou `dashboards:uid:abc123`
`delete_snapshot`	Snapshot	Excluir um snapshot de dashboard pela chave do snapshot	`dashboards:write`	`dashboards:*` ou `dashboards:uid:abc123`
`get_panel_image`	Renderização	Renderizar um dashboard ou painel armazenado — ou uma prévia de provisionamento de um branch do repositório — como imagem PNG	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Provisionamento	Listar repositórios de provisionamento (ex.: fontes git-sync) com URL de origem, branch, estado de sincronização e saúde	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	Provisionamento	Aplicar em dry-run um arquivo de um repositório de provisionamento e relatar erros de validação de admissão	`provisioning.repositories:read`	N/A
`search_docs`	Documentação	Pesquisar documentação do Grafana ou listar grupos de produtos (omitir consulta para listar produtos)	Nenhuma (grafana.com/docs público)	N/A
`get_doc`	Documentação	Buscar uma página de documentação; definir outline_only para cabeçalhos, ou section para recuperação limitada	Nenhuma (grafana.com/docs público)	N/A
* Desabilitado por padrão. Adicione a categoria a `--enabled-tools` para habilitar.

Referência de Flags de CLI

O binário mcp-grafana suporta vários flags de linha de comando para configuração:

Opções de Transporte:

-t, --transport: Tipo de transporte (stdio, sse ou streamable-http) - padrão: stdio
--address: O host e a porta para o servidor SSE/streamable-http - padrão: localhost:8000
--base-path: Caminho base para o servidor SSE/streamable-http. /healthz e /metrics são sempre servidos na raiz do servidor, não sob este prefixo — são endpoints internos apenas para probes e scrapers, e mantê-los fora do prefixo da aplicação facilita expor a API através de um proxy reverso sem também expô-los
--endpoint-path: Caminho do endpoint para o servidor streamable-http, anexado a --base-path - padrão: /mcp
--server-name: Nome do servidor usado no handshake do MCP e no OTel service.name - padrão: mcp-grafana. Substitui a variável de ambiente GRAFANA_MCP_SERVER_NAME
--instructions-append: Texto anexado às instruções do servidor retornadas aos clientes MCP na inicialização, para que todo agente conectado o veja

Segurança de Transporte HTTP (somente SSE / streamable-http):

A validação de Host/Origin é aplicada em todas as rotas no listener do MCP — /sse, /mcp e /healthz / /metrics quando compartilham esse listener — para que um navegador com DNS-rebinding não consiga alcançar nenhum deles. O transporte Stdio não é afetado. --healthz-address e --metrics-address iniciam um listener separado que não é encapsulado.

--allowed-hosts: Lista de permissões separada por vírgulas dos valores do cabeçalho Host. O padrão são variantes de loopback de --address (ex.: localhost:8000,127.0.0.1:8000,[::1]:8000). Um valor que seja interpretado como vazio (não definido, ,, ,, etc.) também recai nos padrões, para que um erro de digitação não possa desabilitar silenciosamente a verificação. Requisições com um cabeçalho Host fora da lista de permissões são rejeitadas com 403. Passe * para desabilitar a validação de Host — só é seguro quando um proxy reverso confiável valida Host. Probes de httpGet do K8s e scrapes externos de /metrics precisarão de um hostname explícito nesta lista, *, um probe de tcpSocket ou uma porta separada (--healthz-address / --metrics-address).
--allowed-origins: Lista de permissões separada por vírgulas dos valores do cabeçalho Origin. Vazia por padrão — qualquer requisição que carregue um cabeçalho Origin é rejeitada (navegadores sempre enviam um para requisições cross-origin, e nenhum navegador deveria chamar este servidor diretamente). Defina uma lista explícita para permitir clientes baseados em navegador, ou * para desabilitar a verificação.
--allow-grafana-url-override: Habilita a seleção de X-Grafana-URL. Recai em GRAFANA_ALLOW_URL_OVERRIDE; desabilitado por padrão. Sem uma lista de permissões, chamadores podem selecionar qualquer URL HTTP(S) que o servidor consiga alcançar.
--allowed-grafana-urls: Lista de permissões opcional, separada por vírgulas, de URLs base exatas do Grafana para substituições de URL. Recai em GRAFANA_ALLOWED_URLS. Requer --allow-grafana-url-override; um flag explicitamente vazio desabilita uma lista herdada.

Autenticação do Chamador (somente SSE / streamable-http):

Opcionalmente, exija que clientes MCP se autentiquem no servidor. Isso é separado das credenciais que o servidor usa para alcançar o Grafana. O Stdio não é afetado.

--server-auth-token: Token Bearer que os chamadores devem enviar como Authorization: Bearer <token>. Recai na variável de ambiente MCP_GRAFANA_SERVER_TOKEN. Quando definido, requisições sem um token válido são rejeitadas com 401 antes de qualquer ferramenta ser executada. Prefira a variável de ambiente para que o segredo não fique visível nos argumentos do processo.

A autenticação do chamador é aplicada somente quando --server-auth-token está definido. Quando não está e o servidor vincula um endereço não-loopback, o servidor inicia, mas registra um erro de segurança — emitido no nível de log error para que não seja ocultado por --log-level (loopback e stdio não são afetados); uma futura versão principal tornará isso um erro de inicialização. Use TLS (ou terminação TLS) sempre que a autenticação do chamador estiver habilitada em um endereço não-loopback. Quando a autenticação do chamador está habilitada, o cabeçalho Authorization validado é removido antes que as requisições alcancem o Grafana; combinar --server-auth-token com GRAFANA_FORWARD_HEADERS=Authorization é rejeitado na inicialização.

Substituições de URL do Grafana (somente SSE / streamable-http):

[!WARNING] Substituições de URL permitem que chamadores MCP selecionem destinos HTTP(S) de saída. Uma lista de permissões limita URLs, mas não autentica chamadores nem vincula tokens a destinos.

Implante atrás de um proxy autenticador que autorize cada destino, substitua os cabeçalhos de URL e token fornecidos pelo cliente e forneça o token correspondente. Restrinja o acesso de rede de saída do servidor a destinos aprovados.

Sem uma lista de permissões, um token de requisição falso pode causar requisições a qualquer serviço HTTP(S) alcançável, incluindo serviços internos e de metadados.

Defina GRAFANA_ALLOW_URL_OVERRIDE=true (ou --allow-grafana-url-override) para habilitar a seleção para uma grande frota. Para restringir destinos, também defina GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (ou --allowed-grafana-urls).

Envie estes cabeçalhos em cada requisição MCP que selecionar um destino:

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

Se --server-auth-token estiver configurado, envie também Authorization: Bearer <MCP caller token>. Isso autentica no servidor MCP e é separado de X-Grafana-Service-Account-Token, que é para a instância do Grafana selecionada. Seu proxy pode enviar um token do Grafana diferente para cada instância; o servidor nunca compartilha um token configurado entre elas. O cabeçalho obsoleto X-Grafana-API-Key também funciona. Um cabeçalho de URL sem um token do Grafana de requisição é rejeitado. Use TLS para requisições recebidas porque elas carregam tokens.

A lista de permissões corresponde a URLs base exatas, incluindo esquema, porta e caminho; curingas não são suportados. A autenticação do Grafana não é uma defesa contra SSRF.

Para uma URL selecionada, o servidor não usa GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, autenticação básica de ambiente, GRAFANA_EXTRA_HEADERS ou certificados de cliente. A verificação TLS permanece habilitada mesmo se --tls-skip-verify estiver definido; um arquivo de CA configurado ainda se aplica. Cabeçalhos explicitamente encaminhados dessa requisição ainda se aplicam. Redirecionamentos e outras requisições de API do Grafana fora da URL base selecionada são bloqueados. Requisições sem X-Grafana-URL mantêm o comportamento usual de GRAFANA_URL e credenciais de ambiente. Esta opção se aplica somente a SSE e streamable HTTP. Para SSE, inclua ambos os cabeçalhos de seleção em cada POST de mensagem; cabeçalhos no GET inicial de SSE não são transferidos para chamadas de ferramenta.

Depuração e Registro:

--debug: Habilita o modo de depuração para registro detalhado de requisições/respostas HTTP
--log-level: Nível de log (debug, info, warn, error) - padrão: info

Opções do Cliente Grafana:

--grafana-timeout: Limite de tempo para requisições feitas pelo cliente Grafana. Aceita strings de duração Go (ex.: 10s, 500ms) - padrão: 10s
--include-args-in-spans: Inclui argumentos de chamadas de ferramenta em spans do OpenTelemetry. Habilite somente em ambientes não-produtivos ou quando os argumentos forem conhecidos por não conter PII - padrão: false

Observabilidade:

--metrics: Habilita o endpoint de métricas Prometheus em /metrics
--metrics-address: Endereço separado para o servidor de métricas (ex.: :9090). Se vazio, as métricas são servidas no servidor principal
--healthz-address: Endereço separado para /healthz (ex.: :8080). Se vazio, /healthz é servido no servidor principal. Compartilha um listener com --metrics-address quando os dois endereços coincidem. Listeners laterais ignoram a validação de Host/Origin.
--slow-request-threshold: Registra um evento quando qualquer requisição MCP (invocação de ferramenta, listagem, leitura de recurso, etc.) levar mais tempo que esta duração. Aceita strings de duração Go (ex.: 500ms, 5s). O padrão 0 desabilita o registro de requisições lentas. Veja a seção Registro de requisições lentas.
--slow-request-log-level: Nível de log para eventos de requisições lentas (info ou warn) - padrão: warn.

Estatísticas de Uso Anônimas:

--usage-stats: Relatório de estatísticas de uso anônimas: enabled, disabled ou log (imprime o relatório que seria enviado para stderr e não envia nada). Substitui a variável de ambiente GRAFANA_USAGE_STATS, que por sua vez substitui DO_NOT_TRACK; qualquer valor não reconhecido desabilita o relatório. Veja a seção Estatísticas de uso anônimas.

Gerenciamento de Sessão:

--session-idle-timeout-minutes: Tempo limite de inatividade de sessão em minutos. Sessões sem atividade por esta duração são automaticamente removidas - padrão: 30. Defina como 0 para desabilitar a remoção de sessões. Relevante somente para transportes SSE e streamable-http. Configuração da Ferramenta:
--enabled-tools: Lista separada por vírgulas de categorias habilitadas - padrão: todas as categorias, exceto admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery e snowflake. Para habilitar categorias desabilitadas, adicione-as à lista (por exemplo, "search,datasource,...,snowflake")
--max-loki-log-limit: Número máximo de linhas de log retornadas por chamada query_loki_logs - padrão: 100. Observação: defina isso em pelo menos 1 abaixo do max_entries_limit_per_query do lado do servidor do Loki para permitir a detecção de truncamento (a ferramenta solicita limit+1 internamente para detectar se existem mais dados).
--loki-guardrail-mode: Salvaguarda de custo de consulta do Loki para query_loki_logs - padrão: off. O Loki não aplica max_query_bytes_read em consultas de log sem um filtro de linha, portanto, um seletor amplo em um intervalo extenso pode escanear terabytes; a salvaguarda exige um seletor de stream seletivo, limita o intervalo de tempo efetivo (incluindo durações de vetor de intervalo como [30d]) e pré-verifica a estimativa de bytes do índice/estatísticas do Loki antes de executar a consulta. shadow registra consultas que seriam bloqueadas, mas permite que sejam executadas (ainda paga o round trip de índice/estatísticas); enforce as rejeita com orientação de reescrita na qual o LLM pode agir. No VictoriaLogs, a salvaguarda se aplica apenas a consultas em formato de seletor ({...}) — quando nenhum seletor é analisado (o formato LogsQL normal sem chaves), a consulta passa integralmente e a verificação de orçamento de bytes nunca se aplica (sem estimativa de índice barata). Fallback de ambiente: GRAFANA_LOKI_GUARDRAIL_MODE.
--loki-guardrail-max-bytes: Bytes máximos que uma única chamada query_loki_logs pode escanear, estimados via API de índice/estatísticas do Loki - padrão: 107374182400 (100 GiB). 0 desabilita a verificação de orçamento de bytes. Fallback de ambiente: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Intervalo de tempo efetivo máximo para uma única chamada query_loki_logs, incluindo durações de vetor de intervalo - padrão: 24h. Aceita strings de duração Go. 0 desabilita a verificação de intervalo. Fallback de ambiente: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers: Correspondências de rótulos LogQL aplicadas com AND em toda consulta nativa do Loki para restringir quais streams de log podem ser lidos (por exemplo, environment=~"prod|staging"). Requer --disable-api. Consulte Imposição de consulta Loki.
--loki-label-enumeration-fallback: O que as ferramentas de enumeração de rótulos fazem quando correspondências impostas negativas não podem escopá-las: reject (padrão) ou unfiltered. Consulte Imposição de consulta Loki.
--disable-search: Desabilitar ferramentas de busca
--disable-datasource: Desabilitar ferramentas de datasource
--disable-incident: Desabilitar ferramentas de incidentes
--disable-prometheus: Desabilitar ferramentas do Prometheus
--disable-write: Desabilitar ferramentas de escrita (operações de criar/atualizar)
--disable-query: Desabilitar ferramentas de consulta (ferramentas que executam uma consulta contra um datasource); ferramentas de metadados e descoberta permanecem disponíveis
--enable-query: Manter as ferramentas de consulta SQL bruta (query_sql, query_influxdb) registradas mesmo sob --disable-write. Equivalente a --enable-write-tools=query_sql,query_influxdb; mantido como uma abreviação para esse caso comum.
--enable-write-tools: Lista separada por vírgulas de nomes de ferramentas individuais para manter registradas mesmo sob --disable-write, para ferramentas cujo comportamento de escrita é escopado o suficiente para optar novamente de forma independente (por exemplo, find_error_pattern_logs,find_slow_requests). Não tem efeito em uma ferramenta cuja categoria inteira está desabilitada, por exemplo, via --disable-sift.
--disable-loki: Desabilitar ferramentas do Loki
--disable-elasticsearch: Desabilitar ferramentas do Elasticsearch e OpenSearch
--disable-quickwit: Desabilitar ferramentas do Quickwit
--disable-influxdb: Desabilitar ferramentas do InfluxDB
--disable-alerting: Desabilitar ferramentas de alertas
--disable-dashboard: Desabilitar ferramentas de dashboards
--disable-oncall: Desabilitar ferramentas do OnCall
--disable-asserts: Desabilitar ferramentas do Asserts
--disable-sift: Desabilitar ferramentas do Sift
--disable-admin: Desabilitar ferramentas administrativas
--disable-pyroscope: Desabilitar ferramentas do Pyroscope
--disable-navigation: Desabilitar ferramentas de navegação
--disable-rendering: Desabilitar ferramentas de renderização (exportação de imagem de painel/dashboard)
--disable-snapshot: Desabilitar ferramentas de snapshot
--disable-cloudwatch: Desabilitar ferramentas do CloudWatch
--disable-cloudlogging: Desabilitar ferramentas do Google Cloud Logging
--disable-examples: Desabilitar ferramentas de exemplos de consulta
--disable-sql: Desabilitar ferramentas de datasource SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Os aliases --disable-clickhouse, --disable-snowflake, --disable-athena também funcionam.
--disable-runpanelquery: Desabilitar ferramentas de execução de consulta de painel
--disable-graphite: Desabilitar ferramentas do Graphite
--disable-provisioning: Desabilitar ferramentas de provisionamento
--disable-agento11y: Desabilitar ferramentas de Observabilidade de Agentes
--disable-assistant: Desabilitar ferramentas do Assistente Grafana
--disable-docs: Desabilitar ferramentas de documentação

Modo Somente Leitura

O sinalizador --disable-write fornece uma maneira de executar o servidor MCP em modo somente leitura, impedindo qualquer operação de escrita na sua instância Grafana. Isso é útil para cenários onde você deseja fornecer acesso seguro e somente leitura, como:

Uso de contas de serviço com permissões limitadas de somente leitura
Fornecimento de dados de observabilidade a assistentes de IA sem capacidades de modificação
Execução em ambientes de produção onde o acesso de escrita deve ser restrito
Cenários de teste e desenvolvimento onde você deseja evitar modificações acidentais

Quando --disable-write está habilitado, as seguintes operações de escrita são desabilitadas:

Ferramentas de Dashboard:

update_dashboard

Ferramentas de Pasta:

create_folder

Ferramentas de Incidentes:

create_incident
add_activity_to_incident
update_incident

Ferramentas de Alertas:

alerting_manage_rules (operações de criar, atualizar, excluir)
alerting_manage_silences (operações de criar, atualizar, excluir)

Ferramentas do OnCall:

update_alert_group

Ferramentas de Anotações:

create_annotation
update_annotation
delete_annotation

Ferramentas do Sift:

find_error_pattern_logs (cria investigações)
find_slow_requests (cria investigações)

Estas apenas criam registros efêmeros de investigação do Sift via API do Sift — nunca tocam em um dashboard, alerta ou datasource do Grafana. Sem elas, list_sift_investigations/get_sift_investigation/get_sift_analysis não têm nada para listar ou obter. Passe --enable-write-tools=find_error_pattern_logs,find_slow_requests para mantê-las registradas sob --disable-write.

Ferramentas de Snapshot:

create_snapshot
delete_snapshot

Ferramentas de Consulta SQL Bruta:

Estas executam qualquer consulta que você fornecer sem inspecioná-la, portanto, podem escrever quando as credenciais do datasource permitirem — query_sql executará um DROP TABLE, query_influxdb executará um DELETE. O modo somente leitura, portanto, as remove. Passe --enable-query para mantê-las quando as credenciais do datasource forem conhecidas como somente leitura.

query_sql
query_influxdb

Ferramentas de Observabilidade de Agentes:

agento11y_manage_evaluators (operações de upsert, excluir, bifurcar, testar avaliador)
agento11y_manage_eval_rules (operações de criar, atualizar, excluir, pré-visualizar regra e guarda)
agento11y_manage_eval_collections (salvar e excluir conversas salvas; criar, atualizar, excluir coleções; adicionar e remover membros de coleção)
agento11y_manage_experiments (operações de atualizar e cancelar experimento)
agento11y_manage_test_suites (criar e atualizar suítes de teste; criar e publicar versões; upsert e excluir casos de teste)

Todas as operações de leitura permanecem disponíveis, permitindo consultar dashboards, executar consultas PromQL/LogQL, listar recursos e recuperar dados. As linguagens de consulta que não podem expressar uma escrita — PromQL, LogQL, TraceQL, o DSL do Elasticsearch, Graphite, CloudWatch — mantêm suas ferramentas de consulta no modo somente leitura; apenas as de SQL bruto listadas acima são removidas.

Modo Sem Consulta

O sinalizador --disable-query remove toda ferramenta que executa uma consulta contra um datasource, mantendo as ferramentas de metadados e descoberta no lugar. Isso é útil quando você deseja um assistente que possa explorar o que existe — datasources, dashboards, nomes de métricas, rótulos, esquemas de tabelas — sem executar consultas potencialmente caras ou que revelem dados, por exemplo, quando a conta de serviço tem datasources:read mas não datasources:query.

É a mais forte das três configurações de consulta e vence sobre --enable-query:

Sinalizadores	Ferramentas de consulta seguras (`query_prometheus`, `query_loki_logs`, `run_panel_query`, …)	Ferramentas de consulta SQL bruta (`query_sql`, `query_influxdb`)
(nenhum)	registradas	registradas
`--disable-write`	registradas	não registradas
`--disable-write --enable-query`	registradas	registradas
`--disable-query`	não registradas	não registradas
`--disable-query --enable-query`	não registradas	não registradas

Quando --disable-query está habilitado, as seguintes ferramentas não são registradas:

Ferramentas do Prometheus:

query_prometheus
query_prometheus_histogram

Ferramentas do Loki:

query_loki_logs
query_loki_patterns

query_loki_stats e analyze_loki_labels permanecem registradas: ambas enviam um seletor ao datasource, mas leem o índice e retornam contagens de stream, chunk e bytes em vez de conteúdo de log.

Ferramentas do Elasticsearch/OpenSearch e Quickwit:

query_elasticsearch
query_quickwit

Ferramentas do InfluxDB (também removidas por --disable-write, veja acima):

query_influxdb

Ferramentas de Datasource SQL (também removidas por --disable-write, veja acima):

query_sql

Ferramentas do Graphite:

query_graphite
query_graphite_density

Ferramentas do CloudWatch:

query_cloudwatch

Ferramentas do Google Cloud Logging:

query_cloud_logging

Ferramentas do Pyroscope:

query_pyroscope

Ferramentas de Execução de Consulta de Painel:

run_panel_query

As categorias elasticsearch, quickwit, influxdb e runpanelquery não contêm mais nada, portanto, não registram nenhuma ferramenta quando as consultas estão desabilitadas. As ferramentas irmãs em todas as outras categorias — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects e assim por diante — permanecem disponíveis.

Observe que --disable-query controla as ferramentas de consulta e o caminho POST para grafana_api_request-/api/ds/query, mas não policia todas as rotas para um datasource. No modo somente leitura, grafana_api_request permite POST para /api/ds/query apenas quando as ferramentas de consulta estão habilitadas (mesma porta que as ferramentas de SQL bruto — bloqueado por --disable-write a menos que --enable-query substitua). get_panel_image, que renderiza um painel no lado do servidor, não é afetado.

Configuração TLS do Cliente (para conexões Grafana):

--tls-cert-file: Caminho para o arquivo de certificado TLS para autenticação do cliente
--tls-key-file: Caminho para o arquivo de chave privada TLS para autenticação do cliente
--tls-ca-file: Caminho para o arquivo de certificado CA TLS para verificação do servidor
--tls-skip-verify: Pular verificação de certificado TLS (inseguro)

Configuração TLS do Servidor (somente transporte streamable-http):

--server.tls-cert-file: Caminho para o arquivo de certificado TLS para HTTPS do servidor
--server.tls-key-file: Caminho para o arquivo de chave privada TLS para HTTPS do servidor

Uso

Este servidor MCP funciona com instâncias Grafana locais e Grafana Cloud. Para Grafana Cloud, use a URL da sua instância (por exemplo, https://myinstance.grafana.net) em vez de http://localhost:3000 nos exemplos de configuração abaixo.

Se estiver usando autenticação por token de conta de serviço, crie uma conta de serviço no Grafana com permissões suficientes para usar as ferramentas que deseja usar, gere um token de conta de serviço e copie-o para a área de transferência para uso no arquivo de configuração. Siga a documentação de conta de serviço do Grafana para obter detalhes sobre como criar tokens de conta de serviço. Dica: Se você não se sentir confortável configurando escopos RBAC de granularidade fina, uma opção mais simples (mas menos restritiva) é atribuir o papel integrado Editor à conta de serviço. Isso concede amplo acesso de leitura/escrita que cobre a maioria das operações do servidor MCP — use-o quando a conveniência superar os requisitos estritos de privilégio mínimo.

Observação: A variável de ambiente GRAFANA_API_KEY está obsoleta e será removida em uma versão futura. Migre para usar GRAFANA_SERVICE_ACCOUNT_TOKEN em vez dela. O nome antigo da variável continuará funcionando para compatibilidade retroativa, mas mostrará avisos de depreciação.

Lendo o token da conta de serviço de um arquivo

Em vez de passar o token inline via GRAFANA_SERVICE_ACCOUNT_TOKEN, você pode apontar GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE para um caminho de arquivo que contenha o token. O arquivo é lido novamente a cada requisição, então tokens rotacionados são detectados automaticamente sem reiniciar o servidor.

Isso é particularmente útil no Kubernetes, onde um Secret montado como volume é atualizado no local quando o Secret subjacente muda (normalmente em ~1 minuto). Combinado com o cache de cliente por requisição — que é baseado no valor do token — um token rotacionado produz transparentemente um novo cliente sem reiniciar o pod e sem tempo de inatividade:

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

Espaços em branco ao redor (incluindo uma nova linha final) são removidos do conteúdo do arquivo. Se ambos GRAFANA_SERVICE_ACCOUNT_TOKEN e GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE estiverem definidos, o token inline tem precedência.

Suporte a Múltiplas Organizações

Você pode especificar com qual organização interagir usando:

Variável de ambiente: Defina GRAFANA_ORG_ID para o ID numérico da organização
Cabeçalho HTTP: Defina X-Grafana-Org-Id ao usar transportes SSE ou HTTP streamable (o cabeçalho tem precedência sobre a variável de ambiente — ou seja, você também pode definir uma organização padrão).

Quando um ID de organização é fornecido, o servidor MCP definirá o cabeçalho X-Grafana-Org-Id em todas as requisições ao Grafana, garantindo que as operações sejam executadas no contexto da organização especificada.

Seleção dinâmica de organização (por chamada)

As opções acima fixam a organização para toda a conexão. Para permitir que uma única conexão direcione diferentes organizações por chamada de ferramenta, inicie o servidor com a flag --dynamic-multi-org. Isso está desativado por padrão.

Quando ativado, toda ferramenta aceita um argumento opcional orgId que substitui a organização da conexão para aquela chamada (controlando tanto o cabeçalho X-Grafana-Org-Id quanto, para APIs de plataforma de aplicativos, o namespace Kubernetes resolvido). Ferramentas de datasource com proxy são adicionalmente descobertas em todas as organizações que a credencial pode acessar. Chamadas que omitem orgId usam a organização padrão da conexão.

Isso só funciona para credenciais que pertencem a mais de uma organização (por exemplo, um usuário ou identidade em nome de); um token de conta de serviço permanece vinculado à sua única organização. Use a ferramenta user_info para descobrir quais valores de orgId são válidos.

Exemplo com ID de organização:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

Cabeçalhos HTTP Personalizados

Você pode adicionar cabeçalhos HTTP arbitrários a todas as requisições da API do Grafana usando a variável de ambiente GRAFANA_EXTRA_HEADERS. O valor deve ser um objeto JSON mapeando nomes de cabeçalhos para valores.

Exemplo com cabeçalhos personalizados:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

Proxy SOCKS5

Você pode rotear todas as requisições que este servidor faz ao Grafana através de um proxy SOCKS5 usando a variável de ambiente GRAFANA_SOCKS5_PROXY. O proxy é limitado ao tráfego do Grafana deste servidor: ele não modifica as variáveis globais HTTP_PROXY/HTTPS_PROXY, e quando definido, substitui a seleção de proxy delas apenas para transportes do Grafana, sem afetar outros servidores MCP ou sua sessão de shell. Quando não definido, o comportamento permanece inalterado.

A URL deve usar o esquema socks5:// ou socks5h:// (Go os trata de forma idêntica: a resolução de nome de host é delegada ao proxy) e pode incluir credenciais, por exemplo, socks5://user:pass@127.0.0.1:1080.

Exemplo:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Uma URL de proxy inválida é um erro de inicialização, e se a construção de uma conexão com proxy falhar em tempo de execução, o servidor falha de forma segura em vez de enviar silenciosamente o tráfego do Grafana diretamente.

Encaminhamento de Cabeçalhos do Cliente (Somente SSE/Streamable-HTTP)

Quando o servidor MCP roda atrás de um gateway ou proxy reverso que gerencia SSO (por exemplo, um AWS ALB com OIDC), o cookie de sessão de cada usuário deve chegar ao Grafana para que ele possa associar a requisição ao usuário autenticado. A variável de ambiente GRAFANA_FORWARD_HEADERS ativa isso especificando uma lista de permissões separada por vírgulas de nomes de cabeçalhos para copiar da requisição HTTP de entrada para cada requisição de saída à API do Grafana.

Isso só se aplica ao usar transportes SSE (-t sse) ou streamable-http (-t streamable-http). Não tem efeito no modo stdio.

Exemplo: encaminhar o cookie de sessão

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

Você pode encaminhar vários cabeçalhos separando-os por vírgulas:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Cabeçalhos encaminhados são mesclados com quaisquer cabeçalhos definidos em GRAFANA_EXTRA_HEADERS. Se um nome de cabeçalho aparecer em ambos, o valor da requisição de entrada tem precedência para aquela requisição.

Cabeçalhos de contexto de rastreamento (traceparent, tracestate, baggage) são a exceção: o servidor propaga o contexto de rastreamento por conta própria, então um valor encaminhado nunca substitui o que ele injeta. Veja observabilidade.

Você tem várias opções para instalar mcp-grafana:
- uvx (recomendado): Se você tem uv instalado, nenhuma configuração extra é necessária — uvx baixará e executará automaticamente o servidor:
```
uvx mcp-grafana
```
- Imagem Docker: Use a imagem Docker pré-construída do Docker Hub.
  
  Importante: O entrypoint da imagem Docker está configurado para executar o servidor MCP em modo SSE por padrão, mas a maioria dos usuários vai querer usar o modo STDIO para integração direta com assistentes de IA como o Claude Desktop:
  1. Modo STDIO: Para o modo stdio, você deve substituir explicitamente o padrão com -t stdio e incluir a flag -i para manter o stdin aberto:
```
docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
```
  Nota — proteja os modos de rede: Nos modos SSE e streamable-http, o contêiner vincula um endereço não loopback (0.0.0.0:8000). Sem um token de chamador, o servidor inicia, mas registra um erro de segurança (no nível de log error, para que não seja ocultado por --log-level; e ele se recusará a iniciar em uma futura versão principal). Defina MCP_GRAFANA_SERVER_TOKEN para exigir um Authorization: Bearer <token> dos clientes (recomendado). O modo STDIO não é afetado. Veja Autenticação do Chamador.
  1. Modo SSE: Neste modo, o servidor roda como um servidor HTTP ao qual os clientes se conectam. Você deve expor a porta 8000 usando a flag -p:
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
```
  1. Modo HTTP Streamable: Neste modo, o servidor opera como um processo independente que pode lidar com múltiplas conexões de clientes. Você deve expor a porta 8000 usando a flag -p: Para este modo, você deve substituir explicitamente o padrão com -t streamable-http
```
docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
```
  Para modo HTTP streamable HTTPS com certificados TLS do servidor:
```
docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key
```
- Baixar binário: Baixe a versão mais recente de mcp-grafana na página de releases e coloque-a em seu $PATH.
- Compilar a partir do código-fonte: Se você tem um toolchain Go instalado, também pode compilar e instalar a partir do código-fonte, usando a variável de ambiente GOBIN para especificar o diretório onde o binário deve ser instalado. Isso também deve estar em seu $PATH.
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```
- Implantar no Kubernetes usando Helm: use o Helm chart do repositório helm-charts do Grafana
```
helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp
```

Adicione a configuração do servidor ao seu arquivo de configuração do cliente. Por exemplo, para o Claude Desktop:

Se estiver usando uvx:

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Se estiver usando o binário:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Nota: se você vir Error: spawn mcp-grafana ENOENT no Claude Desktop, você precisa especificar o caminho completo para mcp-grafana.

Se estiver usando Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Nota: O argumento -t stdio é essencial aqui porque substitui o modo SSE padrão na imagem Docker.

Usando VSCode com servidor MCP remoto

Se você está usando VSCode e executando o servidor MCP em modo SSE (que é o padrão ao usar a imagem Docker sem substituir o transporte), certifique-se de que seu .vscode/settings.json inclua o seguinte:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Para modo HTTP streamable HTTPS com certificados TLS do servidor:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

Modo de Depuração

Você pode ativar o modo de depuração para o transporte do Grafana adicionando a flag -debug ao comando. Isso fornecerá logs detalhados de requisições e respostas HTTP entre o servidor MCP e a API do Grafana, o que pode ser útil para solução de problemas.

Para usar o modo de depuração com a configuração do Claude Desktop, atualize sua configuração da seguinte forma:

Se estiver usando o binário:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Se estiver usando Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Nota: Como na configuração padrão, o argumento -t stdio é necessário para substituir o modo SSE padrão na imagem Docker.

Configuração TLS

Se sua instância do Grafana estiver atrás de mTLS ou exigir certificados TLS personalizados, você pode configurar o servidor MCP para usar certificados personalizados. O servidor suporta as seguintes opções de configuração TLS:

--tls-cert-file: Caminho para o arquivo de certificado TLS para autenticação do cliente
--tls-key-file: Caminho para o arquivo de chave privada TLS para autenticação do cliente
--tls-ca-file: Caminho para o arquivo de certificado CA TLS para verificação do servidor
--tls-skip-verify: Pular verificação de certificado TLS (inseguro, use apenas para testes)

Exemplo com autenticação de certificado do cliente:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Exemplo com Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

A configuração TLS é aplicada a todos os clientes HTTP usados pelo servidor MCP, incluindo:

O cliente principal da OpenAPI do Grafana
Clientes de datasource Prometheus
Clientes de datasource Loki
Clientes de gerenciamento de incidentes
Clientes de investigação Sift
Clientes de alertas
Clientes Asserts

Exemplos de uso direto via CLI:

Para testes com certificados autoassinados:

./mcp-grafana --tls-skip-verify -debug

Com autenticação de certificado do cliente:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

Com certificado CA personalizado apenas:

./mcp-grafana --tls-ca-file /path/to/ca.crt

Uso programático:

Se você está usando esta biblioteca programaticamente, também pode criar funções de contexto habilitadas para TLS:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

Validação de URL:

Ao chamar NewGrafanaClient diretamente (stdio ou construção programática), pré-valide URLs para evitar um panic alcançável:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

Configuração TLS do Servidor (Somente Transporte HTTP Streamable)

Ao usar o transporte HTTP streamable (-t streamable-http), você pode configurar o servidor MCP para servir HTTPS em vez de HTTP. Isso é útil quando você precisa proteger a conexão entre seu cliente MCP e o próprio servidor.

O servidor suporta as seguintes opções de configuração TLS para o transporte HTTP streamable:

--server.tls-cert-file: Caminho para o arquivo de certificado TLS para HTTPS do servidor (obrigatório para TLS)
--server.tls-key-file: Caminho para o arquivo de chave privada TLS para HTTPS do servidor (obrigatório para TLS)

Nota: Essas flags são completamente separadas das flags TLS do cliente documentadas acima. As flags TLS do cliente configuram como o servidor MCP se conecta ao Grafana, enquanto essas flags TLS do servidor configuram como os clientes se conectam ao servidor MCP ao usar o transporte HTTP streamable.

Exemplo com servidor HTTP streamable HTTPS:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

Isso iniciaria o servidor MCP na porta HTTPS 8443. Os clientes então se conectariam a https://localhost:8443/ em vez de http://localhost:8000/.

Exemplo Docker com TLS do servidor:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Endpoint de Verificação de Saúde

Ao usar os transportes SSE (-t sse) ou HTTP streamable (-t streamable-http), o servidor MCP expõe um endpoint de verificação de saúde em /healthz. Este endpoint pode ser usado por balanceadores de carga, sistemas de monitoramento ou plataformas de orquestração para verificar se o servidor está rodando e aceitando conexões.

Endpoint: GET /healthz

Resposta:

Código de Status: 200 OK
Corpo: ok

Exemplo de uso:

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

Nota: O endpoint de verificação de saúde só está disponível ao usar transportes SSE ou HTTP streamable. Não está disponível ao usar o transporte stdio (-t stdio), pois stdio não expõe um servidor HTTP.

Estatísticas de Uso Anônimas

O servidor pode reportar estatísticas anônimas de uso sobre si mesmo para a Grafana Labs: quais ferramentas foram chamadas, quantas dessas chamadas falharam e como o servidor está configurado. Um relatório cobre um processo do servidor — não um usuário e não uma conversa — e é enviado a cada 4h, além de uma vez no encerramento. O relatório está desabilitado por padrão nesta versão — o endpoint de recebimento ainda não está ativo — e uma versão futura mudará o padrão para habilitado com a mesma opção de exclusão.

Argumentos de ferramentas, nomes de recursos, consultas, linhas de log, mensagens de erro e credenciais nunca são enviados. Flags são registradas apenas por nome, nunca por valor, e a instância Grafana é descrita apenas como cloud ou self_hosted — nunca por URL, hostname, slug de stack ou org. Nada é por usuário, por sessão ou por cliente: não há identificador de sessão no fio e nenhuma maneira de atribuir uma chamada de ferramenta a um cliente específico.

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1 também desabilita o relatório, seguindo a convenção DO_NOT_TRACK entre ferramentas. Apenas 1 tem efeito, só pode desabilitar, e tanto --usage-stats quanto GRAFANA_USAGE_STATS o substituem, então um host que o define globalmente ainda pode optar por reativar um servidor.

GRAFANA_USAGE_STATS_ENDPOINT altera o destino. Não é uma opção de exclusão.

Para a lista completa de campos, o que nunca é enviado, como ler os dados e suas limitações, veja Estatísticas de uso anônimas.

Observabilidade

O servidor MCP suporta métricas Prometheus, rastreamento distribuído OpenTelemetry e exportação de logs OpenTelemetry, seguindo as convenções semânticas OTel MCP. O rastreamento e a exportação de logs são configurados por meio de variáveis de ambiente padrão OTEL_* e funcionam com qualquer transporte.

Nota: mcp-grafana atualmente suporta apenas o transporte OTLP/gRPC para traces e logs. OTEL_EXPORTER_OTLP_PROTOCOL (e suas variantes _TRACES_PROTOCOL / _LOGS_PROTOCOL) não são honradas — gRPC é usado independentemente.

Métricas

Ao usar os transportes SSE ou HTTP streamable, habilite as métricas Prometheus com a flag --metrics:

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

Métricas disponíveis:

Métrica	Tipo	Descrição
`mcp_server_operation_duration_seconds`	Histograma	Duração das operações MCP (labels: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`mcp_server_session_duration_seconds`	Histograma	Duração das sessões de cliente MCP (labels: `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histograma	Duração das requisições do servidor HTTP (de otelhttp)

Nota: As métricas estão disponíveis apenas ao usar os transportes SSE ou HTTP streamable. Elas não estão disponíveis com o transporte stdio.

Quando o guarda-costas Loki (--loki-guardrail-mode) está habilitado, mais quatro contadores registram suas decisões:

Métrica	Tipo	Descrição
`mcp_loki_guardrail_admitted_total`	Contador	Consultas que passaram em todas as verificações habilitadas (labels: `backend`)
`mcp_loki_guardrail_would_block_total`	Contador	Consultas que falharam em uma verificação no modo `shadow` e foram executadas mesmo assim (labels: `backend`, `reason`)
`mcp_loki_guardrail_blocked_total`	Contador	Consultas rejeitadas no modo `enforce` (labels: `backend`, `reason`)
`mcp_loki_guardrail_fail_open_total`	Contador	Consultas que o guarda-costas não conseguiu avaliar e admitiu (labels: `backend`, `cause`)

reason é um de selector, range, bytes; cause é um de unparseable, estimate_failed; backend é um de loki, victorialogs, unknown. Uma consulta que aciona várias verificações é contada uma vez, rotulada com a verificação que foi executada primeiro (selector, depois range, depois bytes), então os quatro contadores particionam a população protegida. Veja Observabilidade para saber como lê-los durante um rollout de shadow → enforce.

Incorporadores de biblioteca devem definir GrafanaConfig.MeterProvider (a contraparte de métricas de GrafanaConfig.Logger): o guarda-costas roda dentro de um manipulador de ferramenta, então não tem opção de construtor, e um processo que instala um MeterProvider global noop descartaria cada gravação.

Registro de requisições lentas

A flag --slow-request-threshold emite um evento de log estruturado sempre que uma requisição MCP (invocação de ferramenta, listagem, leitura de recurso, etc.) excede a duração fornecida. É útil para diagnosticar consultas e chamadas de ferramenta lentas sem se afogar no log de depuração completo.

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

O evento de log carrega estes atributos estruturados:

Atributo	Descrição
`mcp.method`	O método MCP (ex.: `tools/call`, `tools/list`, `resources/read`)
`duration`	Duração observada da requisição
`threshold`	Limite configurado
`tool`	Nome da ferramenta (presente apenas para métodos `tools/call`)
`error`	Valor de erro, quando a requisição falhou (contexto de melhor esforço; o conteúdo é controlado pelo encapsulamento de erro upstream)
`error.type`	Classificação de erro de cardinalidade limitada (`_OTHER` para erros sem tipo)

O registro de requisições lentas funciona em todos os transportes (incluindo stdio) e não requer --metrics. O limite padrão de 0 o desabilita completamente. Ferramentas proxy fluem através de tools/call e são cobertas automaticamente.

Rastreamento

O rastreamento distribuído é configurado por meio de variáveis de ambiente padrão OTEL_* e funciona independentemente da flag --metrics. Quando OTEL_EXPORTER_OTLP_ENDPOINT (ou o OTEL_EXPORTER_OTLP_TRACES_ENDPOINT específico de sinal) está definido, o servidor exporta traces via OTLP/gRPC:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

Os spans de chamadas de ferramenta seguem a nomenclatura semconv (tools/call <tool_name>) e incluem atributos como gen_ai.tool.name, mcp.method.name e mcp.session.id. O servidor também suporta propagação de contexto de trace W3C do campo _meta de requisições de chamada de ferramenta.

Logs

Quando OTEL_EXPORTER_OTLP_ENDPOINT (ou o OTEL_EXPORTER_OTLP_LOGS_ENDPOINT específico de sinal) está definido, o servidor também exporta logs estruturados via OTLP/gRPC além da saída stderr de texto simples existente. A ponte otelslog anexa automaticamente trace_id e span_id do span ativo, então os registros de log correlacionam com os traces que o servidor já emite.

Traces e logs resolvem seus endpoints independentemente, então os dois sinais podem ser habilitados separadamente: definir apenas OTEL_EXPORTER_OTLP_TRACES_ENDPOINT habilita o rastreamento sem exportação de logs, definir apenas OTEL_EXPORTER_OTLP_LOGS_ENDPOINT habilita a exportação de logs sem rastreamento, e o OTEL_EXPORTER_OTLP_ENDPOINT genérico habilita ambos.

Se você usa o OTEL_EXPORTER_OTLP_ENDPOINT genérico, mas quer desabilitar a exportação de logs (ex.: seu backend não suporta o LogsService), defina:

OTEL_LOGS_EXPORTER=none

Isso impede que o servidor crie um exportador de logs OTLP independentemente da configuração do endpoint, evitando erros como unknown service opentelemetry.proto.collector.logs.v1.LogsService.

O registro stderr permanece inalterado quando o registro OTLP está habilitado; você pode continuar confiando nos logs do contêiner ou canalizar stderr para /dev/null se preferir.

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

O transporte é OTLP/gRPC (porta padrão 4317). Os logs podem ser enviados diretamente para qualquer backend gerenciado que aceite OTLP/gRPC — por exemplo, Grafana Cloud — apontando OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (ou o OTEL_EXPORTER_OTLP_ENDPOINT genérico) para o endpoint gRPC remoto e fornecendo autenticação via OTEL_EXPORTER_OTLP_LOGS_HEADERS (ou OTEL_EXPORTER_OTLP_HEADERS), espelhando o exemplo de rastreamento acima. Um coletor OTel local é opcional — útil para fan-out, loteamento ou roteamento multi-backend, mas não obrigatório.

As variantes específicas de sinal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT e OTEL_EXPORTER_OTLP_LOGS_COMPRESSION são honradas e substituem suas contrapartes genéricas OTEL_EXPORTER_OTLP_* — veja a especificação do exportador OTel para a lista completa e regras de precedência.

Se o coletor configurado estiver inacessível, os registros de log são armazenados em buffer na memória (fila padrão: 2048) e os registros mais antigos são descartados quando a fila enche. O processo continua sem bloquear o serviço. Configure um coletor OTel local se precisar de buffer sem perdas durante interrupções.

Os logs também são exportados sob o transporte stdio, o que facilita centralizar logs de instâncias locais mcp-grafana invocadas por clientes IDE.

Exemplo Docker com métricas, rastreamento e logs:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Aplicação de consultas Loki

--loki-enforced-matchers permite que um operador restrinja quais streams de log Loki o servidor pode ler, aplicando um E lógico de um conjunto fixo de correspondências de labels LogQL em cada consulta nativa-Loki que o servidor emite. Isso é útil quando um datasource contém streams que não devem ser expostos (ex.: logs que podem carregar informações sensíveis), mas você não pode restringir o acesso na camada Grafana ou Loki (OSS não tem controle de acesso por label por datasource ou por usuário).

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

Como funciona:

As correspondências são analisadas uma vez na inicialização (entrada inválida aborta o servidor) e anexadas a cada seletor de stream em cada consulta. Como o Loki aplica E lógico nas correspondências dentro de um seletor, uma consulta de usuário só pode estreitar resultados dentro dos limites aplicados — nunca pode ampliá-los. Um seletor de usuário que conflita com a política (ex.: pedindo {namespace="vault"} sob uma exclusão) simplesmente retorna nada.
Cobre query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names e list_loki_label_values.
Falha fechado: qualquer consulta que não possa ser analisada é rejeitada em vez de enviada sem filtro.
Datasources VictoriaLogs usam LogsQL, que não pode ser reescrito com segurança, então eles são recusados completamente enquanto a aplicação está habilitada.
Correspondências puramente negativas não podem escopar os endpoints de enumeração de labels (Loki rejeita um seletor independente sem correspondência positiva). Controle esse caso extremo com --loki-label-enumeration-fallback (reject por padrão, ou unfiltered para permitir enumeração sem escopo de metadados de label — linhas de log nunca são expostas). Correspondências positivas/allowlist não são afetadas.

[!IMPORTANT] A aplicação se aplica apenas às ferramentas de consulta Loki. Outras ferramentas podem alcançar dados de log Loki por caminhos que nunca tocam o backend aplicado, então para a restrição realmente valer, você também deve desabilitá-las:

--disable-api — grafana_api_request pode consultar o proxy do datasource Loki diretamente (bypass total).

--disable-rendering — get_panel_image renderiza painéis Loki no lado do servidor, produzindo imagens com linhas de log sem restrição.

--disable-sift — Investigações Sift analisam logs Loki no lado do servidor em todos os streams.

--disable-assistant — ask_assistant delega para o Grafana Assistant, que lê Loki no lado do servidor em todos os streams. Apenas registrado quando ferramentas de escrita estão habilitadas, então --disable-write também o fecha.

O servidor registra um aviso na inicialização nomeando cada um desses que ainda está habilitado. run_panel_query é seguro (reutiliza o caminho de consulta aplicado). Ferramentas Tempo consultam traces, não logs Loki, então não são um bypass. Snapshots de dashboard (--disable-snapshot) também podem incorporar dados de painéis de log capturados fora da aplicação.

Solução de problemas

Compatibilidade de versão Grafana

Se você encontrar o seguinte erro ao usar ferramentas relacionadas a datasource:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

Isso normalmente indica que você está usando uma versão Grafana anterior à 9.0. O endpoint da API /datasources/uid/{uid} foi introduzido no Grafana 9.0, e operações de datasource falharão em versões anteriores.

Solução: Atualize sua instância Grafana para a versão 9.0 ou posterior para resolver esse problema.

Desenvolvimento

Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md primeiro — ele cobre o que pertence a este servidor e como propor isso. Se você estiver adicionando uma nova ferramenta, por favor abra uma proposta de ferramenta antes de escrever o código. Toda ferramenta habilitada por padrão é enviada ao modelo em cada solicitação de cada usuário, então preferimos discutir a ideia a recusar um pull request finalizado. Correções de bugs, documentação, testes e novos parâmetros em ferramentas existentes não precisam de proposta — basta enviar um PR.

Este projeto é escrito em Go. Instale o Go seguindo as instruções para sua plataforma.

Para executar o servidor localmente no modo STDIO (que é o padrão para desenvolvimento local), use:

make run

Para executar o servidor localmente no modo SSE, use:

go run ./cmd/mcp-grafana --transport sse

Você também pode executar o servidor usando o transporte SSE dentro de uma imagem Docker personalizada. Assim como a imagem Docker publicada, o entrypoint desta imagem personalizada usa o modo SSE por padrão. Para construir a imagem, use:

make build-image

E para executar a imagem no modo SSE (o padrão), use:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Se você precisar executá-la no modo STDIO, substitua a configuração de transporte:

docker run -it --rm mcp-grafana:latest -t stdio

Testes

Existem três tipos de testes disponíveis:

Testes Unitários (sem dependências externas necessárias):

make test-unit

Você também pode executar testes unitários com:

make test

Testes de Integração (requerem containers docker em execução):

make test-integration

Testes em Nuvem (requerem instância Grafana na nuvem e credenciais):

make test-cloud

Nota: Os testes em nuvem são configurados automaticamente no CI. Para desenvolvimento local, você precisará configurar sua própria instância Grafana Cloud e credenciais.

Testes de integração mais abrangentes exigirão uma instância Grafana em execução localmente na porta 3000; você pode iniciar uma com Docker Compose:

docker-compose up -d

Os testes de integração podem ser executados com:

make test-all

Se você estiver adicionando mais ferramentas, adicione testes de integração para elas. Os testes existentes devem ser um bom ponto de partida.

Linting

Para fazer lint do código, execute:

make lint

Isso inclui um linter personalizado que verifica vírgulas não escapadas em tags de struct jsonschema. As vírgulas nos campos description devem ser escapadas com \\, para evitar truncamento silencioso. Você pode executar apenas este linter com:

make lint-jsonschema

Consulte a documentação do Linter JSONSchema para mais detalhes.

Licença

Este projeto é licenciado sob a Apache License, Versão 2.0.