Grafana

Servidor MCP do Grafana

Um servidor do Model Context Protocol (MCP) para Grafana.

Ele 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 (por exemplo, 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 o Grafana Cloud, substitua GRAFANA_URL pela URL da sua instância (por exemplo, https://myinstance.grafana.net). Consulte Uso para ver mais opções de instalação, incluindo Docker, binário e Helm.

Requisitos

• É necessária a versão 9.0 ou posterior do Grafana para obter funcionalidade completa. Alguns recursos, especialmente as operações relacionadas a fontes de dados, podem não funcionar corretamente em versões anteriores devido à ausência de endpoints da API.

Recursos

Atualmente, os seguintes recursos estão disponíveis no servidor MCP. Esta lista é apenas informativa e não representa um roteiro nem um compromisso com recursos futuros.

Dashboards

• Pesquisar dashboards: Encontre dashboards por título, UID da pasta, tag ou status de favorito
• Obter dashboard por UID: Recupere os detalhes completos de um dashboard usando seu identificador exclusivo. Passe version opcional para carregar um snapshot salvo em vez do dashboard atual. Aviso: dashboards grandes podem consumir uma parte significativa da janela de contexto.
• Listar versões do dashboard: Liste as versões salvas de um dashboard como metadados compactos (número da versão, autor, data e hora, mensagem de salvamento)
• Obter resumo do dashboard: Obtenha uma visão geral compacta de um dashboard, incluindo título, número de painéis, tipos de painel, 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 (por exemplo, $.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: é necessário o JSON completo do dashboard, que pode consumir uma grande quantidade da janela de contexto.
• Aplicar patch a um dashboard: Aplique alterações específicas a um dashboard sem precisar do JSON completo, reduzindo significativamente o consumo da janela de contexto para modificações direcionadas
• Obter consultas dos painéis e informações das fontes de dados: Obtenha o título, a string de consulta e as informações da fonte de dados (incluindo UID e tipo, se disponíveis) de cada painel de um dashboard

Executar consulta de painel

Observação: As ferramentas de execução de consultas de painel ficam desativadas por padrão. Para ativá-las, adicione runpanelquery à 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. Os painéis Infinity são executados quando a consulta usa o parser backend ou jq-backend (as consultas do Google Sheets sempre o fazem); o parser padrão simple e os parsers UQL e GROQ funcionam apenas no navegador. Os painéis Neo4j no plugin kniepdennis-neo4j-datasource executam a consulta Cypher por meio do plugin, que abre sessões somente leitura. Os painéis Elasticsearch interpolam variáveis na consulta Lucene usando o formato lucene, como o Grafana faz, e os histogramas de data automáticos usam o mesmo intervalo que $__interval.

Gerenciamento da janela de contexto

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

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

Fontes de dados

• Listar e buscar informações de fontes de dados: Veja todas as fontes de dados configuradas e recupere informações detalhadas sobre cada uma.
  • Tipos de fontes de dados compatíveis: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.
• Recursos de fontes de dados: Cada fonte de dados a que você tem acesso também é exposta como um recurso MCP em grafana://datasources/{uid}, para que você possa anexá-la diretamente a uma conversa (por exemplo, com @ no Claude Code), em vez de o modelo precisar buscá-la. Desativado junto com as ferramentas de fontes de dados.

Exemplos de consultas

Observação: As ferramentas de exemplos de consultas ficam desativadas por padrão. Para ativá-las, adicione examples à flag --enabled-tools.

• Obter exemplos de consultas: Recupere exemplos de consultas para diferentes tipos de fontes de dados e aprenda a sintaxe de consulta.

Consultas Prometheus

• Consultar Prometheus: Execute consultas PromQL (compatíveis com consultas instantâneas e de intervalo de métricas) em fontes de dados Prometheus.
• Consultar metadados do Prometheus: Recupere metadados de métricas, nomes de métricas, nomes de labels e valores de labels de fontes de dados Prometheus.
• Consultar percentis de histogramas: Calcule valores de percentis de histogramas (p50, p90, p95, p99) usando histogram_quantile.

Consultas Loki

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

Consultas InfluxDB

Observação: As ferramentas InfluxDB ficam desativadas por padrão. Para ativá-las, adicione influxdb à flag --enabled-tools.

• Consultar InfluxDB: Execute consultas em fontes de dados InfluxDB usando InfluxQL (v1.x) ou Flux (v2.x). O dialeto é inferido da configuração da fonte de dados ou pode ser definido explicitamente pelo parâmetro dialect.

Consultas a fontes de dados SQL

Observação: As ferramentas SQL ficam desativadas por padrão. Para ativá-las, adicione sql à flag --enabled-tools. Os aliases de compatibilidade clickhouse, snowflake e athena também funcionam.

As ferramentas SQL unificadas são compatíveis com ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL e BigQuery por meio de um único conjunto de ferramentas. As consultas passam pelos plugins de fontes de dados do Grafana, portanto, a autenticação é gerenciada pela configuração da fonte de dados — as credenciais nunca são vistas pelo servidor MCP.

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

Para BigQuery, configure o plugin grafana-bigquery-datasource no Grafana. A descoberta usa database para o projeto e schema para o conjunto de dados. Se database for omitido, o projeto assume como padrão o valor da fonte de dados defaultProject e, em seguida, o endpoint /defaultProjects do plugin (incluindo a descoberta do projeto GCE). Os metadados são obtidos somente por meio de APIs, sem jobs de consulta nem varreduras de tabelas. As descrições de colunas e os tipos aninhados são incluídos; o plugin omite descrições/tipos de tabelas, possibilidade de valores nulos das colunas e valores padrão.

As consultas BigQuery exigem referências qualificadas a tabelas, como `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring} para variáveis de string escapadas. Os limites de linhas não limitam os bytes verificados nem os custos das consultas.

Consultas CloudWatch

Observação: As ferramentas CloudWatch ficam desativadas por padrão. Para ativá-las, adicione cloudwatch à flag --enabled-tools.

• Listar namespaces do CloudWatch: Descubra os namespaces disponíveis do AWS CloudWatch.
• Listar métricas do CloudWatch: Liste as 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 intervalos de tempo.
• Listar grupos de logs do CloudWatch: Descubra grupos de logs, opcionalmente filtrados por prefixo de nome.
• Listar campos de grupos de logs do CloudWatch: Descubra os campos disponíveis em um grupo de logs.
• Consultar CloudWatch Logs: Execute consultas do CloudWatch Logs Insights em um ou mais grupos de logs.

Consultas Google Cloud Logging

Observação: As ferramentas Google Cloud Logging ficam desativadas por padrão. Para ativá-las, adicione cloudlogging à flag --enabled-tools. Requer a versão 1.8.0 ou posterior do plugin Google Cloud Logging datasource (googlecloud-logging-datasource), que exige o Grafana 11.2 ou posterior. Versões mais antigas do plugin retornam um layout de resposta diferente, e query_cloud_logging informa um erro solicitando uma atualização.

• Listar projetos do Cloud Logging: Descubra os IDs de projetos GCP dos quais a fonte de dados pode ler logs.
• Listar buckets e visualizações do Cloud Logging: Descubra buckets de logs e visualizações de logs para delimitar uma consulta.
• Consultar Cloud Logging: Execute filtros da linguagem de consulta do Cloud Logging (por exemplo, resource.type="k8s_container" AND severity>=ERROR) com intervalo de tempo e limite; retorna entradas da mais recente para a mais antiga, com gravidade, corpo, labels e ID de trace. A autenticação GCP é gerenciada pela configuração da fonte de dados.

Consultas Graphite

Observação: As ferramentas Graphite ficam desativadas por padrão. Para ativá-las, adicione graphite à flag --enabled-tools.

• Consultar Graphite: Execute consultas da API render do Graphite em uma fonte de dados Graphite.
• Listar métricas Graphite: Navegue e descubra caminhos de métricas Graphite.
• Listar tags Graphite: Liste as tags Graphite e os valores de tags disponíveis.
• Consultar densidade Graphite: Consulte a densidade de métricas Graphite para um padrão especificado.

Consultas Elasticsearch/OpenSearch

Observação: As ferramentas Elasticsearch/OpenSearch ficam desativadas por padrão. Para ativá-las, adicione elasticsearch à flag --enabled-tools.

• Consultar Elasticsearch/OpenSearch: Execute consultas de pesquisa em fontes de dados Elasticsearch ou OpenSearch usando a sintaxe de consulta Lucene ou Elasticsearch Query DSL. Oferece suporte a filtros por intervalo de tempo e à recuperação de logs, métricas ou quaisquer dados indexados. Retorna documentos com o índice, o ID, os campos de origem e uma pontuação de relevância opcional.

Consultas Quickwit

Observação: As ferramentas Quickwit ficam desativadas por padrão. Para ativá-las, adicione quickwit à flag --enabled-tools.

• Consultar Quickwit: Execute consultas de pesquisa em fontes de dados Quickwit usando a sintaxe de consulta Lucene ou um subconjunto do Elasticsearch Query DSL compatível. Oferece suporte a filtros por intervalo de tempo e à recuperação de logs ou outros documentos indexados. Retorna documentos com o índice, o ID, os campos de origem e uma pontuação de relevância opcional.

Observabilidade de agentes

Observação: As ferramentas de observabilidade de agentes ficam desativadas por padrão e funcionam apenas no Grafana Cloud. Para ativá-las, adicione agento11y à 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 muito mais) em um intervalo de tempo. Os resultados da pesquisa incluem contagens de erros, resumos de avaliações, resumos de avaliações automatizadas e IDs de rastreamento.
• Obter detalhes da conversa: Busque uma conversa específica com todas as suas gerações, incluindo prompts e saídas.
• Obter detalhes e pontuações da geração: Busque uma geração específica pelo ID e suas pontuações de avaliação (avaliador, chave da pontuação, valor, aprovada, 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, todas as ferramentas com seus esquemas JSON e os modelos em que foi executado), percorra o histórico de versões de um agente e compare os agregados das pontuações de avaliação por versão. As versões efetivas são hashes sha256: que nunca são afetados por alterações nas ferramentas; para um agente que não informa uma versão própria, elas geram um hash do prompt de sistema, portanto uma edição do prompt cria uma nova versão. As linhas do catálogo e das versões incluem um token_estimate, que vale a pena verificar antes de buscar um prompt completo.
• Inspecionar avaliadores e modelos: Leia os avaliadores que geraram uma pontuação, os modelos dos quais eles foram derivados e os provedores e modelos de juiz disponíveis para avaliadores com juiz LLM. Com as ferramentas de gravação habilitadas, também crie, bifurque, teste e exclua avaliadores.
• Inspecionar regras de avaliação e proteções: Leia as regras de avaliação assíncronas que vinculam avaliadores ao tráfego de produção e as proteções (regras de hook) que são executadas em linha e podem emitir avisos ou negar. Com as ferramentas de gravação habilitadas, também crie, atualize, visualize e exclua essas regras. As gravações e as operações preview_rule e test_evaluator, que não persistem alterações, precisam da permissão grafana-agento11y-app.eval:write, concedida pela função Agento11y Admin.
• Organizar conversas e coleções salvas: Leia as conversas salvas (favoritos que atribuem 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 as ferramentas de gravação habilitadas, também adicione uma conversa aos favoritos, crie e edite coleções e adicione ou remova membros. Essas gravações precisam da mesma permissão grafana-agento11y-app.eval:write.
• Ler e editar conjuntos de testes: Liste os conjuntos de testes versionados usados em experimentos offline, leia um conjunto com todo o seu histórico de versões e percorra os casos de teste de uma versão. Com as ferramentas de gravação habilitadas, também crie um conjunto, altere seu nome ou suas tags, abra uma versão de rascunho, publique-a e grave ou exclua seus casos de teste. Uma versão publicada é imutável, portanto, para editá-la, é preciso abrir um novo rascunho. Essas gravações precisam de grafana-agento11y-app.eval:write.
• Ler experimentos offline: Liste as execuções de avaliação de um conjunto de testes e leia uma delas com sua taxa geral de aprovação, custo e totais de tokens. Aprofunde-se em um relatório por caso de teste para consultar as tentativas, suas pontuações com a explicação de cada juiz e os metadados dos artefatos. Com as ferramentas de gravação habilitadas, também altere o nome ou as tags de um experimento e cancele um experimento em execução; essas ações precisam de grafana-agento11y-app.eval:write. Os experimentos são criados por executores do SDK, não por esta ferramenta.

Grafana Assistant

Observação: As ferramentas do Assistant estão desabilitadas por padrão e exigem que o plugin Grafana Assistant (grafana-assistant-app) esteja instalado na instância de destino do Grafana. Elas também são ferramentas de gravação (o assistant pode alterar o estado da stack), portanto são ignoradas quando --disable-write está definido. Para habilitá-las, adicione assistant à flag --enabled-tools.

• Perguntar ao assistant: Envie um prompt em linguagem natural ao Grafana Assistant e aguarde a resposta completa em texto. O assistant pode usar ferramentas, métricas, logs e outros dados de contexto da stack — um escopo mais amplo do que executar uma única consulta isolada a uma fonte de dados. Passe o contextId retornado em uma chamada subsequente para continuar a mesma conversa. Tarefas complexas podem levar vários minutos; a chamada fica bloqueada até a resposta ser concluída ou a solicitação expirar (5 minutos).

Incidentes

• Pesquisar, criar e atualizar incidentes: Gerencie incidentes no Grafana Incident, incluindo pesquisar, criar, adicionar atividades e ler ou definir campos personalizados.
• Recursos de incidentes: Incidentes ativos iniciados nos últimos 30 dias também são expostos como recursos MCP em grafana://irm/incidents/{id}, para que você possa anexar um diretamente a uma conversa (por exemplo, com @ no Claude Code). Desabilitado junto com as ferramentas de incidentes.

Alertas

• Listar e buscar informações de regras de alerta: Veja as regras de alerta e seus status (disparado/normal/erro etc.) no Grafana. Compatível com 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 pelo UID.
• Gerenciar o roteamento de alertas: Veja políticas de notificação, pontos de contato e intervalos de tempo. Compatível com pontos de contato gerenciados pelo Grafana e receptores de fontes de dados externas do Alertmanager (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 atualmente de plantão: Veja quais usuários estão atualmente de plantão em uma escala.
• Listar equipes e usuários: Veja todas as equipes e usuários do OnCall.
• Listar grupos de alertas: Veja e filtre grupos de alertas do Grafana OnCall por vários critérios, incluindo estado, integração, rótulos e intervalo de tempo.
• Obter detalhes de grupos de alertas: Recupere informações detalhadas sobre um grupo de alertas específico pelo ID.

Administração

Observação: As ferramentas de administração estão desabilitadas por padrão. Para habilitá-las, inclua admin na flag --enabled-tools.

• Listar equipes: Veja todas as equipes configuradas no Grafana.
• Listar usuários: Veja todos os usuários de 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 de uma função: Obtenha detalhes de uma função específica do Grafana pelo UID.
• Listar atribuições de uma função: Liste todos os usuários, equipes e contas de serviço atribuídos a uma função.
• Listar funções de usuários: Liste todas as funções atribuídas a um ou mais usuários.
• Listar funções de equipes: Liste todas as funções atribuídas a uma ou mais equipes.
• Listar permissões de um recurso: Liste todas as permissões definidas para um recurso específico (dashboard, fonte de dados, pasta etc.).
• Descrever um recurso do Grafana: Liste as permissões disponíveis e os recursos 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 é administrador do Grafana (servidor), a organização atual e as organizações às quais a credencial pode acessar (com as funções). Use isso para descobrir valores válidos de orgId para solicitações de várias organizações.

Navegação

• Gerar links diretos: Crie URLs precisas de links diretos para recursos do Grafana, em vez de depender de suposições do LLM sobre URLs.
  • Links de dashboards: Gere links diretos para dashboards usando seu UID (por exemplo, http://localhost:3000/d/dashboard-uid)
  • Links de painéis: Crie links para painéis específicos dentro de dashboards 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"}}). Versões do Grafana anteriores à 10.2 não reconhecem panes, então o formato legado ?left={...} é emitido para essas versões.
  • Suporte a intervalos 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 dashboard ou intervalos de atualização

Anotações

• Obter anotações: Consulte anotações com filtros. Compatível com intervalo de tempo, UID do dashboard, tags e modo de correspondência.
• Criar anotação: Crie uma nova anotação em um dashboard ou painel.
• Criar anotação do 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).
• Aplicar patch a uma anotação: Atualize apenas campos específicos de uma anotação (atualização parcial).
• Excluir anotação: Exclua permanentemente uma anotação pelo ID.
• Obter tags de anotações: Liste as tags de anotação disponíveis com filtragem opcional.

Snapshots

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

Renderização

• Obter imagem de painel ou dashboard: Renderize um painel do dashboard do Grafana ou o dashboard completo como imagem PNG. Retorna a imagem como dados codificados em base64 para uso em relatórios, alertas ou apresentações. Por padrão, usa 1000×750 pixels CSS para um painel ou 1200×900 para um dashboard completo, ambos na escala 1. O Explore usa 1000×1000 na escala 1 por padrão. As dimensões estão sujeitas aos limites da área de visualização do renderizador de imagens. É possível personalizar dimensões, intervalo de tempo, tema, escala e variáveis do dashboard. Também é possível renderizar dashboards ainda não aplicados de uma ramificação de repositório de provisionamento (por exemplo, uma prévia de PR do git-sync) por meio do parâmetro opcional provisioningPreview.
  • Observação: requer que o serviço Grafana Image Renderer esteja instalado e configurado.

Provisionamento

• Listar repositórios de provisionamento: Liste os repositórios de provisionamento configurados para esta instância do Grafana (por exemplo, fontes do git-sync), retornando o slug de cada repositório junto com sua URL de origem, ramificação, caminho, estado de sincronização e integridade.
• Validar arquivo de provisionamento: Faça uma simulação de aplicação de um arquivo de um repositório de provisionamento em uma determinada ramificação ou commit. Retorna se o arquivo seria aceito, a ação sobre o recurso (criar/atualizar), o tipo de recurso de destino e quaisquer erros de validação estruturados — a mesma interface de admissão usada pelo comentarista de PR do Grafana.

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 determinadas funcionalidades ou se não quer ocupar muito espaço da janela de contexto. Para desabilitar uma categoria de ferramentas, use a flag --disable-<category> ao iniciar o servidor. Por exemplo, para desabilitar as ferramentas do OnCall, use --disable-oncall, ou para desabilitar a geração de links diretos de navegação, use --disable-navigation.

Permissões RBAC

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

Dica: se você não conhece bem o RBAC do Grafana ou quer uma configuração mais rápida e simples em vez de configurar vários escopos granulares, você pode atribuir uma função integrada, como Editor, à conta de serviço. A função Editor concede amplo acesso de leitura e gravação, permitindo a maioria das operações do servidor MCP; ela é menos granular (e, portanto, menos restritiva) do que os escopos aplicados manualmente, então use-a somente quando a conveniência for mais importante do que o princípio do menor privilégio.

Observação: As ferramentas do OnCall e de outros plugins são autorizadas por ações de plugins, como grafana-irm-app.schedules:read. A função básica Viewer inclui as ações de leitura, e a função Editor inclui as ações de gravação. As ferramentas de incidentes precisam apenas de plugins.app:access; o IRM autoriza ações de incidentes pela função básica.

Ações no formato group/resource:verb, como dashboard.grafana.app/dashboards:get, aplicam-se somente a tokens de acesso em nome de outra pessoa. Uma conta de serviço precisa apenas das outras ações listadas.

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

Escopos RBAC

Os escopos definem os recursos específicos aos quais as permissões se aplicam. Cada ação exige a combinação adequada de permissão e 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 painéis
  • 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 somente a uma fonte de dados Prometheus específica
  • dashboards:uid:abc123 - Acesso somente ao painel com UID abc123
  • folders:uid:xyz789 - Acesso somente à pasta com UID xyz789
  • teams:id:5 - Acesso somente à equipe com ID 5
  • global.users:id:123 - Acesso somente 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 somente instâncias específicas do Prometheus e do Loki

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

• Acesso específico a painéis: Leia somente painéis 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	Admin*	Listar todas as equipes	teams:read	teams:* ou teams:id:1
list_users_by_org	Admin*	Listar usuários em uma organização, com pesquisa e paginação	org.users:read	global.users:* ou global.users:id:123
list_all_roles	Admin*	Listar todas as funções do Grafana	roles:read	roles:*
get_role_details	Admin*	Obter detalhes de uma função do Grafana	roles:read	roles:uid:editor
get_role_assignments	Admin*	Listar atribuições de uma função	roles:read, teams.roles:read, users.roles:read	roles:uid:editor
list_user_roles	Admin*	Listar funções de usuários	users.roles:read	global.users:id:123
list_team_roles	Admin*	Listar funções de equipes	teams.roles:read	teams:id:7
get_resource_permissions	Admin*	Listar permissões de um recurso	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:uid:abcd1234
get_resource_description	Admin*	Descrever um tipo de recurso do Grafana	dashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:read	dashboards:*
user_info	Usuário	Identidade atual, recursos e organizações acessíveis	Nenhum	—
search_dashboards	Pesquisa	Pesquisar painéis por consulta, UID da pasta, caminho da pasta, tag ou favoritos	dashboards:read, folders:read	dashboards:* ou dashboards:uid:abc123
search_folders	Pesquisa	Pesquisar pastas por título	folders:read	folders:* ou folders:uid:xyz789
get_dashboard_by_uid	Painel	Obter um painel por uid, opcionalmente uma versão salva	dashboard.grafana.app/dashboards:get, dashboards:read, dashboards:write	dashboards:uid:abc123
list_dashboard_versions	Painel	Listar versões salvas de um painel (versão, autor, horário, mensagem)	dashboards:read, dashboards:write	dashboards:uid:abc123
update_dashboard	Painel	Atualizar ou criar um novo painel	dashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:read	dashboards:*, folders:* ou folders:uid:xyz789
get_dashboard_panel_queries	Painel	Obter o título do painel, consultas, UID e tipo da fonte de dados de um painel	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
run_panel_query	RunPanelQuery*	Executar uma ou mais consultas de painel	dashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:read	dashboards:uid:*, datasources:uid:*
get_dashboard_property	Painel	Extrair partes específicas de um painel usando expressões JSONPath	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
get_dashboard_summary	Painel	Obter um resumo compacto de um painel sem o JSON completo	dashboard.grafana.app/dashboards:get, dashboards:read	dashboards:uid:abc123
create_folder	Dashboard	Criar uma pasta	folders:create, folders:read, folders:write	folders:*
list_datasources	Datasources	Listar fontes de dados	datasources:read	datasources:*
get_datasource	Datasources	Obter uma fonte de dados por UID ou nome	datasources:read	datasources:uid:prometheus-uid
check_datasources_health	Datasources	Verificar a integridade de uma ou mais fontes de dados	datasources:query, datasources:read	datasources:uid:*
create_datasource	Datasources	Criar uma fonte de dados	datasources:create, datasources:read	datasources:*
update_datasource	Datasources	Atualizar uma fonte de dados	datasources:read, datasources:write	datasources:* ou datasources:uid:abc123
get_query_examples	Examples*	Obter consultas de exemplo para um tipo de fonte de dados	None	datasources:*
query_prometheus	Prometheus	Consultar métricas usando PromQL sem abrir um gráfico	datasources:query, datasources:read	datasources:uid:prometheus-uid
render_grafana_app	Rendering	Executar uma ferramenta de consulta habilitada e exibir o resultado no Grafana App interativo	datasources:query, datasources:read	datasources:* ou datasources:uid:<uid>
list_prometheus_metric_metadata	Prometheus	Listar metadados de métricas	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_metric_names	Prometheus	Listar nomes de métricas disponíveis	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_names	Prometheus	Listar nomes de rótulos que correspondem a um seletor	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_prometheus_label_values	Prometheus	Listar valores de um rótulo específico	datasources:query, datasources:read	datasources:uid:prometheus-uid
query_prometheus_histogram	Prometheus	Calcular valores de percentis de histogramas	datasources:query, datasources:read	datasources:uid:prometheus-uid
list_incidents	Incident	Listar incidentes no Grafana Incident, opcionalmente com os valores dos campos personalizados	plugins.app:access	N/A
create_incident	Incident	Criar um incidente no Grafana Incident, opcionalmente definindo campos personalizados	plugins.app:access	N/A
add_activity_to_incident	Incident	Adicionar um item de atividade a um incidente no Grafana Incident	plugins.app:access	N/A
update_incident	Incident	Atualizar um incidente no Grafana Incident (status, gravidade, título ou campos personalizados)	plugins.app:access	N/A
get_incident	Incident	Obter um único incidente por ID, incluindo seus campos personalizados	plugins.app:access	N/A
list_incident_custom_fields	Incident	Listar os campos personalizados configurados para incidentes, com seus tipos e opções de seleção	plugins.app:access	N/A
query_loki_logs	Loki	Consultar e recuperar logs usando LogQL (consultas de log ou de métricas)	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_names	Loki	Listar todos os nomes de rótulos disponíveis nos logs	datasources:query, datasources:read	datasources:uid:loki-uid
list_loki_label_values	Loki	Listar valores de um rótulo de log específico	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_stats	Loki	Obter estatísticas sobre fluxos de logs	datasources:query, datasources:read	datasources:uid:loki-uid
query_loki_patterns	Loki	Consultar padrões de log detectados para identificar estruturas comuns	datasources:query, datasources:read	datasources:uid:loki-uid
analyze_loki_labels	Loki	Auditar uma estratégia de rótulos do Loki (dinâmica ou estática) e, opcionalmente, diagnosticar o desempenho das consultas	datasources:query, datasources:read	datasources:uid:loki-uid
suggest_loki_alloy_label_config	Config	Gerar um trecho de Alloy loki.process que imponha os rótulos aprovados	None	N/A
query_influxdb	InfluxDB*	Consultar o InfluxDB usando InfluxQL (v1) ou Flux (v2)	datasources:query, datasources:read	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:read	datasources:uid:*
list_sql_tables	SQL*	Listar tabelas em uma fonte de dados SQL	datasources:query, datasources:read	datasources:uid:*
describe_sql_table	SQL*	Obter o esquema de colunas de uma tabela	datasources:query, datasources:read	datasources:uid:*
query_sql	SQL*	Executar consultas SQL com substituição de macros	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_namespaces	CloudWatch*	Listar namespaces disponíveis do AWS CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_metrics	CloudWatch*	Listar métricas em um namespace	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimensions	CloudWatch*	Listar dimensões de uma métrica	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_dimension_values	CloudWatch*	Listar valores de uma chave de dimensão	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch	CloudWatch*	Executar consultas de métricas do CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_groups	CloudWatch*	Listar grupos de logs do CloudWatch	datasources:query, datasources:read	datasources:uid:*
list_cloudwatch_log_group_fields	CloudWatch*	Listar campos descobertos em um grupo de logs	datasources:query, datasources:read	datasources:uid:*
query_cloudwatch_logs	CloudWatch*	Executar consultas do CloudWatch Logs Insights	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_projects	Cloud Logging*	Listar projetos do GCP acessíveis por uma fonte de dados do Google Cloud Logging	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_buckets	Cloud Logging*	Listar buckets de logs em um projeto do GCP	datasources:query, datasources:read	datasources:uid:*
list_cloud_logging_views	Cloud Logging*	Listar visualizações de registros em um bucket de registros	datasources:query, datasources:read	datasources:uid:*
query_cloud_logging	Cloud Logging*	Consultar registros com a linguagem de consulta do Cloud Logging	datasources:query, datasources:read	datasources:uid:*
query_elasticsearch	Elasticsearch/OpenSearch*	Consultar Elasticsearch ou OpenSearch usando a sintaxe Lucene ou Query DSL	datasources:query, datasources:read	datasources:uid:datasource-uid
query_quickwit	Quickwit*	Consultar Quickwit usando a sintaxe Lucene ou Query DSL	datasources:query, datasources:read	datasources:uid:quickwit-uid
alerting_rules_read	Alerting	Listar e inspecionar regras de alerta (listar, obter, versões)	alert.rules.external:read, alert.rules:read, datasources:read, folders:read	folders:* ou folders:uid:alerts-folder
alerting_rules_write	Alerting	Criar, atualizar e excluir regras gerenciadas pelo Grafana ou criar explicitamente regras gerenciadas pela fonte de dados	alert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:read	folders:*, ou datasources:uid:<uid> para criação externa
alerting_manage_routing	Alerting	Gerenciar políticas de notificação, pontos de contato e intervalos de tempo	alert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:get	Escopo global
alerting_routing_write	Alerting	Criar pontos de contato gerenciados pelo Grafana por padrão ou criar explicitamente receptores externos do Alertmanager	alert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:read	Global, ou datasources:uid:<uid> para criação externa
alerting_silences_read	Alerting	Listar e inspecionar silenciamentos de alertas (listar, obter)	alert.instances:read, alert.silences:read	Escopo global
alerting_silences_write	Alerting	Criar, atualizar e expirar silenciamentos de alertas	alert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:write	Escopo global
list_oncall_schedules	OnCall	Listar escalas do Grafana OnCall	grafana-irm-app.schedules:read, plugins.app:access	Escopos específicos do plugin
get_oncall_shift	OnCall	Obter detalhes de um turno específico do OnCall	grafana-irm-app.schedules:read, plugins.app:access	Escopos específicos do plugin
get_current_oncall_users	OnCall	Obter os usuários que estão de plantão no momento em uma escala específica	grafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:access	Escopos específicos do plugin
list_oncall_teams	OnCall	Listar equipes do Grafana OnCall	grafana-irm-app.user-settings:read, plugins.app:access	Escopos específicos do plugin
list_oncall_users	OnCall	Listar usuários do Grafana OnCall	grafana-irm-app.user-settings:read, plugins.app:access	Escopos específicos do plugin
list_alert_groups	OnCall	Listar grupos de alertas do Grafana OnCall com opções de filtragem	grafana-irm-app.alert-groups:read, plugins.app:access	Escopos específicos do plugin
get_alert_group	OnCall	Obter um grupo de alertas específico do Grafana OnCall pelo ID	grafana-irm-app.alert-groups:read, plugins.app:access	Escopos específicos do plugin
update_alert_group	OnCall	Confirmar, desfazer a confirmação, resolver ou desfazer a resolução de um grupo de alertas	grafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:access	Escopos específicos do plugin
list_pyroscope_label_names	Pyroscope	Listar nomes de rótulos que correspondem a um seletor	datasources:query, datasources:read	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:read	datasources:uid:pyroscope-uid
list_pyroscope_profile_types	Pyroscope	Listar tipos de perfil disponíveis	datasources:query, datasources:read	datasources:uid:pyroscope-uid
query_pyroscope	Pyroscope	Consultar perfis, métricas ou ambos no Pyroscope	datasources:query, datasources:read	datasources:uid:pyroscope-uid
get_assertions	Asserts	Obter o resumo de asserções de uma entidade específica	plugins.app:access	Escopos específicos do plugin
agento11y_manage_conversations	Agent Observability*	Listar, pesquisar e buscar conversas de LLM do Grafana Agent Observability	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	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.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_agents	Agent Observability*	Ler o catálogo de agentes: listar agentes, obter uma versão completa de um agente, listar o histórico de versões e agregados de pontuação por versão	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access	N/A
agento11y_manage_evaluators	Agent Observability*	Gerenciar avaliadores, modelos de avaliador e o catálogo de juízes (listar, obter, inserir ou atualizar, bifurcar, testar, excluir)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; com gravações habilitadas, também grafana-agento11y-app.eval:write	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.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; com gravações habilitadas, também grafana-agento11y-app.eval:write	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.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; com gravações habilitadas, também grafana-agento11y-app.eval:write	N/A
agento11y_manage_experiments	Agent Observability*	Ler experimentos offline, suas tentativas, pontuações, metadados de artefatos e facetas de filtro; atualizar e cancelar um experimento	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; com gravações habilitadas, também grafana-agento11y-app.eval:write	N/A
agento11y_manage_test_suites	Agent Observability*	Gerenciar os conjuntos de testes usados pelos experimentos offline, suas versões e seus casos de teste (listar, obter, criar, atualizar, rascunhar, publicar, inserir ou atualizar, excluir)	grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; com gravações habilitadas, também grafana-agento11y-app.eval:write	N/A
ask_assistant	Assistant*	Enviar um prompt ao Grafana Assistant e retornar a resposta completa em texto (várias interações via contextId)	grafana-assistant-app.chats:access, plugins.app:access	Escopos específicos do plugin
generate_deeplink	Navigation	Gerar URLs de links diretos precisas para recursos do Grafana	None	N/A
get_annotations	Annotations	Buscar anotações com filtros	annotations:read	annotations:* ou annotations:id:123
create_annotation	Annotations	Criar uma nova anotação (formato padrão ou Graphite)	annotations:create	annotations:*
update_annotation	Annotations	Atualizar campos específicos de uma anotação (atualização parcial)	annotations:read, annotations:write	annotations:*
delete_annotation	Annotations	Excluir uma anotação por ID	annotations:delete	annotations:*
get_annotation_tags	Annotations	Listar tags de anotação com filtragem opcional	annotations:read	annotations:*
list_snapshots	Snapshot	Listar snapshots de dashboards com filtros opcionais de consulta e limite	snapshots:read	N/A
get_snapshot	Snapshot	Obter metadados do snapshot e o conteúdo do dashboard pela chave do snapshot	None	N/A
create_snapshot	Snapshot	Criar um snapshot de dashboard a partir de um conteúdo completo de dashboard	dashboards:read, snapshots:create	dashboards:uid:abc123
delete_snapshot	Snapshot	Excluir um snapshot de dashboard pela chave do snapshot	dashboards:write, snapshots:delete	dashboards:uid:abc123
get_panel_image	Rendering	Renderizar um dashboard ou painel armazenado, uma prévia de provisionamento ou uma visualização ad hoc do Explore como imagem PNG	dashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:read	dashboards:uid:abc123
list_provisioning_repositories	Provisioning	Listar repositórios de provisionamento (por exemplo, fontes git-sync) com URL de origem, branch, estado de sincronização e integridade	provisioning.grafana.app/repositories:list, provisioning.repositories:read	N/A
validate_provisioning_file	Provisioning	Fazer uma simulação de aplicação de um arquivo de um repositório de provisionamento e relatar erros de validação de admissão	dashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:read	N/A
search_docs	Docs	Pesquisar a documentação do Grafana ou listar grupos de produtos (omita a consulta para listar produtos)	None	N/A
get_doc	Docs	Buscar uma página da documentação; defina outline_only para títulos ou section para uma busca delimitada	None	N/A
search_tempo_traces	Tempo	Pesquisar traces com TraceQL	datasources:query, datasources:read	datasources:uid:tempo-uid
query_tempo_metrics	Tempo	Calcular métricas a partir de traces com TraceQL	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_trace	Tempo	Buscar um trace por ID	datasources:query, datasources:read	datasources:uid:tempo-uid
diff_tempo_traces	Tempo	Comparar dois traces	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_names	Tempo	Listar nomes de atributos de span e recurso	datasources:query, datasources:read	datasources:uid:tempo-uid
list_tempo_attribute_values	Tempo	Listar valores de um atributo de trace	datasources:query, datasources:read	datasources:uid:tempo-uid
get_tempo_traceql_docs	Tempo	Obter a documentação do TraceQL	None	N/A
query_graphite	Graphite*	Consultar métricas do Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
query_graphite_density	Graphite*	Consultar a densidade de métricas do Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_metrics	Graphite*	Listar métricas do Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
list_graphite_tags	Graphite*	Listar tags do Graphite	datasources:query, datasources:read	datasources:uid:graphite-uid
get_plugin	Plugins	Obter um plugin instalado	plugins.app:access	N/A
search_plugin_information	Plugins	Pesquisar o catálogo de plugins do grafana.com	None	N/A
install_plugin	Plugins	Instalar um plugin	plugins:install	N/A
grafana_api_request	API	Chamar um endpoint da API HTTP do Grafana	None	Depende do endpoint
* Desativado por padrão. Adicione a categoria a --enabled-tools para habilitar.

A ferramenta render_grafana_app exibe métricas e traces em hosts MCP compatíveis quando a renderização e as categorias de consulta correspondentes estão habilitadas. As ferramentas de consulta de origem retornam texto e dados estruturados para análise. Consulte MCP Apps para ver as instruções de configuração e incorporação da biblioteca.

Referência de flags da CLI

O binário mcp-grafana oferece suporte a várias 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: Host e porta do servidor SSE/streamable-http - padrão: localhost:8000
• --base-path: Caminho base do servidor SSE/streamable-http. /healthz e /metrics são sempre servidos na raiz do servidor, não sob esse prefixo — são endpoints internos, usados apenas por probes e scrapers, e mantê-los fora do prefixo da aplicação facilita expor a API por meio de um proxy reverso sem também expô-los
• --endpoint-path: Caminho do endpoint do servidor streamable-http, anexado a --base-path - padrão: /mcp
• --sse-keepalive: Intervalo entre solicitações de ping enviadas a cada cliente SSE, para que proxies reversos e balanceadores de carga não fechem um fluxo de eventos ocioso (o que encerra a sessão). Defina um valor abaixo do tempo limite de inatividade do proxy, por exemplo, 30s atrás do valor padrão de 60s de proxy-read-timeout do ingress-nginx. Um cliente é desconectado após 3 pings consecutivos sem resposta durante metade do intervalo cada. Aceita strings de duração do Go, mínimo de 1s - padrão: 0 (desativado). Aplica-se somente a --transport sse
• --server-name: Nome do servidor usado no handshake MCP e no service.name do OTel - 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 durante a inicialização, para que todos os agentes conectados o vejam

Quando --address usa a porta 0, o sistema operacional aloca uma porta livre e o servidor grava atomicamente o endereço vinculado em mcp-grafana-address no diretório de trabalho. O arquivo é criado com o modo 0600.

[!NOTE] No SSE, os cabeçalhos por solicitação não chegam às chamadas de ferramentas: X-Grafana-Service-Account-Token / X-Grafana-API-Key, X-Grafana-Org-Id e os cabeçalhos listados em GRAFANA_FORWARD_HEADERS não têm efeito; as chamadas de ferramentas usam as credenciais do ambiente do servidor, e as substituições de X-Grafana-URL não funcionam. Use streamable-http quando cada chamador precisar de sua própria URL, credenciais ou organização do Grafana.

Segurança do transporte HTTP (somente SSE / streamable-http):

A validação de Host/Origin é aplicada a todas as rotas no listener MCP — /sse, /mcp e /healthz / /metrics quando compartilham esse listener — para que um navegador sujeito a DNS rebinding não consiga acessar nenhuma delas. O transporte stdio não é afetado. --healthz-address e --metrics-address iniciam um listener separado que não é protegido por essa camada.

• --allowed-hosts: Lista de permissões, separada por vírgulas, de valores do cabeçalho Host. O padrão são as variantes de loopback de --address (por exemplo, localhost:8000,127.0.0.1:8000,[::1]:8000). Um valor que resulte vazio após a análise (não definido, ,, , etc.) também usa os valores padrão, para que um erro de digitação não desative a verificação silenciosamente. Solicitações com um cabeçalho Host fora da lista de permissões são rejeitadas com 403. Passe * para desativar a validação de Host — isso só é seguro quando um proxy reverso confiável valida Host. As probes do K8s httpGet e as coletas externas de /metrics precisarão de um nome de host explícito nesta lista, *, uma probe tcpSocket ou uma porta separada (--healthz-address / --metrics-address).
• --allowed-origins: Lista de permissões, separada por vírgulas, de valores do cabeçalho Origin. Vazia por padrão — qualquer solicitação que contenha um cabeçalho Origin é rejeitada (navegadores sempre enviam um em solicitações entre origens, e nenhum navegador deve chamar este servidor diretamente). Defina uma lista explícita para permitir clientes baseados em navegador ou * para desativar a verificação.
• --allow-grafana-url-override: Habilita a seleção de X-Grafana-URL. Usa GRAFANA_ALLOW_URL_OVERRIDE como alternativa; desativado por padrão. Sem uma lista de permissões, os chamadores podem selecionar qualquer URL HTTP(S) que o servidor consiga acessar.
• --allowed-grafana-urls: Lista de permissões opcional, separada por vírgulas, de URLs base exatas do Grafana para substituições de URL. Usa GRAFANA_ALLOWED_URLS como alternativa. Requer --allow-grafana-url-override; uma flag explicitamente vazia desativa uma lista herdada.

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

Opcionalmente, exija que os clientes MCP se autentiquem no servidor. Isso é separado das credenciais que o servidor usa para acessar o Grafana. O transporte stdio não é afetado.

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

A autenticação do chamador só é aplicada quando --server-auth-token está definido. Quando não está definido e o servidor se vincula a um endereço que não seja de 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 transformará isso em um erro de inicialização. Use TLS (ou terminação TLS) sempre que a autenticação do chamador estiver habilitada em um endereço que não seja de loopback. Quando a autenticação do chamador está habilitada, o cabeçalho Authorization validado é removido antes que as solicitações cheguem ao Grafana; combinar --server-auth-token com GRAFANA_FORWARD_HEADERS=Authorization é rejeitado na inicialização.

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

[!WARNING] As substituições de URL permitem que chamadores MCP selecionem destinos HTTP(S) de saída. Uma lista de permissões limita as URLs, mas não autentica os chamadores nem vincula tokens aos 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 aos destinos aprovados.

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

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

Envie estes cabeçalhos em cada solicitaçã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 é destinado à instância selecionada do Grafana. Seu proxy pode enviar um token do Grafana diferente para cada instância; o servidor nunca compartilha um único 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 na solicitação é rejeitado. Use TLS para as solicitações recebidas, pois elas transportam tokens.

A lista de permissões corresponde a URLs base exatas, incluindo esquema, porta e caminho; não há suporte a curingas. 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 do ambiente, GRAFANA_EXTRA_HEADERS nem certificados de cliente. A verificação TLS permanece habilitada mesmo se --tls-skip-verify estiver definido; um arquivo de CA configurado continua sendo aplicado. Os cabeçalhos encaminhados explicitamente dessa solicitação continuam sendo aplicados. Redirecionamentos e outras solicitações à API do Grafana fora da URL base selecionada são bloqueados. Solicitações sem X-Grafana-URL mantêm o comportamento habitual de GRAFANA_URL e das credenciais do ambiente. Esta opção aplica-se somente a streamable HTTP. Não funciona com SSE, que não encaminha cabeçalhos por solicitação às chamadas de ferramentas; nesse caso, uma URL selecionada é usada sem o token do chamador, e as chamadas falham.

Depuração e registro em log:

• --debug: Habilita o modo de depuração para registrar detalhes de solicitaçõ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 solicitações feitas pelo cliente Grafana. Aceita strings de duração do Go (por exemplo, 10s, 500ms) - padrão: 30s
• --allow-cross-origin-redirects: Permite que clientes Grafana de saída sigam redirecionamentos para um esquema, host ou porta diferentes. O padrão é false; GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS é a alternativa de ambiente. Habilitar isso pode enviar credenciais do Grafana ao destino do redirecionamento. URLs do Grafana selecionadas por solicitação continuam vinculadas ao destino selecionado.
• --include-args-in-spans: Inclui argumentos de chamadas de ferramentas nos spans do OpenTelemetry. Habilite somente em ambientes que não sejam de produção ou quando se sabe que os argumentos não contêm PII - padrão: false

Observabilidade:

• --metrics: Habilita o endpoint de métricas do Prometheus em /metrics
• --metrics-address: Endereço separado para o servidor de métricas (por exemplo, :9090). Se estiver vazio, as métricas serão servidas no servidor principal
• --healthz-address: Endereço separado para /healthz (por exemplo, :8080). Se estiver vazio, /healthz será servido no servidor principal. Compartilha um listener com --metrics-address quando os dois endereços coincidem. Listeners auxiliares ignoram a validação de Host/Origin.
• --slow-request-threshold: Registra um evento quando qualquer solicitação MCP (invocação de ferramenta, listagem, leitura de recurso etc.) demora mais do que esta duração. Aceita strings de duração do Go (por exemplo, 500ms, 5s). O padrão 0 desativa o registro de solicitações lentas. Consulte a seção Registro de solicitações lentas.
• --slow-request-log-level: Nível de log para eventos de solicitaçõ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 em stderr o relatório que seria enviado 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 desativa os relatórios. Consulte a seção Estatísticas de uso anônimas. Configuração de ferramentas:

• --enabled-tools: Lista separada por vírgulas de categorias habilitadas — padrão: todas as categorias, exceto admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, dsquery, 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 esse valor 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 há mais dados).

• --loki-guardrail-mode: Limite de proteção contra consultas dispendiosas do Loki para query_loki_logs — padrão: off. O Loki não aplica max_query_bytes_read a consultas de log sem um filtro de linhas, portanto, um seletor amplo em um intervalo extenso pode varrer terabytes; o limite exige um seletor de fluxo específico, limita o intervalo de tempo efetivo (incluindo durações de vetores de intervalo como [30d]) e verifica previamente 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 há o custo da ida e volta ao índice/estatísticas); enforce as rejeita com orientações de reescrita que o LLM pode aplicar. No VictoriaLogs, o limite se aplica somente a consultas com formato de seletor ({...}) — quando nenhum seletor é analisado (o formato normal do LogsQL sem chaves), a consulta passa sem restrições, e a verificação do orçamento de bytes nunca se aplica (não há estimativa barata do índice). Alternativa de ambiente: GRAFANA_LOKI_GUARDRAIL_MODE.

• --loki-guardrail-max-bytes: Número máximo de bytes que uma única chamada query_loki_logs pode varrer, estimado pela API de índice/estatísticas do Loki — padrão: 107374182400 (100 GiB). 0 desativa a verificação do orçamento de bytes. Alternativa 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 vetores de intervalo — padrão: 24h. Aceita strings de duração do Go. 0 desativa a verificação do intervalo. Alternativa de ambiente: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.

• --prometheus-guardrail-mode: Limite de proteção contra consultas do Prometheus para query_prometheus, query_prometheus_histogram e as consultas do Prometheus de run_panel_query — padrão: off. O limite restringe o intervalo de tempo efetivo de uma consulta e o número de pontos por série solicitados, antes que a consulta chegue à fonte de dados. Uma política de seletor independente e opcional pode exigir uma restrição positiva de rótulo não vazia, além do nome da métrica, em cada seletor de vetor; consulte política de seletor para ver exemplos e limites. shadow registra consultas que seriam bloqueadas, mas permite que sejam executadas; enforce as rejeita com orientações de reescrita que o LLM pode aplicar (run_panel_query informa isso na entrada errors do resultado para esse painel). Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_MODE.

• --prometheus-guardrail-require-selective-labels: Exige que cada seletor de vetor inclua uma restrição positiva de rótulo não vazia, além do nome da métrica. Padrão: false; independente dos orçamentos de intervalo e de pontos, inclusive quando ambos são 0. Aplica-se somente quando o modo do limite não é off. Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS. Valores explícitos da CLI, incluindo false, substituem o ambiente.

• --prometheus-guardrail-max-range: Intervalo de tempo efetivo máximo para uma única consulta PromQL — padrão: 192h. O intervalo efetivo é o próprio intervalo de tempo da consulta (zero para consultas instantâneas) mais a janela mais longa de vetor de intervalo ou subconsulta na expressão; os intervalos de subconsultas aninhadas são somados, portanto max_over_time(rate(x[5m])[30d:1m]) lê 30d5m. Aceita strings de duração do Go; portanto, escreva 192h, não 8d. 0 desativa a verificação do intervalo. Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE.

• --prometheus-guardrail-max-points: Número máximo de pontos por série que uma consulta de intervalo pode solicitar, floor(range / step) + 1 — padrão: 11000, o limite por série do próprio Prometheus. As orientações indicam o menor stepSeconds que seja suficiente. 0 desativa a verificação de pontos. Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS.

• --prometheus-guardrail-max-metric-cardinality: Política opcional de escopo do TSDB. Padrão: 0 (desativada). Um nome exato de métrica com contagem de séries acima desse limite exige um correspondedor exato não vazio em um rótulo de escopo configurado. Ativa somente quando o modo não é off. Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_METRIC_CARDINALITY.

• --prometheus-guardrail-cardinality-cache-ttl: Tempo de vida dos instantâneos do TSDB em cache. Padrão: 10m; 0 também usa 10m. Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_CACHE_TTL.

• --prometheus-guardrail-cardinality-scope-labels: Rótulos separados por vírgulas cujos correspondedores exatos não vazios satisfazem a política de cardinalidade. Padrão: job,instance,namespace,pod,service,cluster; se estiver vazio, usa esses padrões. __name__ não é permitido. Alternativa de ambiente: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_SCOPE_LABELS. Configurações explícitas da CLI substituem as variáveis de ambiente correspondentes.

  Limitações do limite de proteção do Prometheus: a verificação de pontos calcula o orçamento da resolução solicitada, não do número de séries, amostras ou avaliações de subconsultas, e o Grafana pode alinhar o intervalo ou ampliar o passo. Os modificadores offset e @ são ignorados. Macros do Grafana, como $__rate_interval e $__range, são preenchidas antes da medição da expressão, usando os valores adotados pelo Grafana ($__rate_interval é quatro vezes o passo). Expressões que o limite ainda não consegue analisar (por exemplo, as que contêm variáveis de painel como $window, ou sintaxe aceita apenas por outro dialeto) são verificadas somente com base no intervalo de tempo e no passo da própria consulta e, caso contrário, são executadas. run_panel_query não tem parâmetro de passo; portanto, amplia seu passo de 1 minuto em intervalos longos para permanecer dentro de 11000 pontos, como o Grafana faz, ou dentro de um --prometheus-guardrail-max-points menor no modo enforce.

• --prometheus-enforced-matchers: Correspondedores de rótulos PromQL aplicados com AND a todas as consultas nativas do Prometheus para restringir quais séries podem ser lidas (por exemplo, environment=~"prod|staging"). Requer --disable-api. Consulte aplicação de políticas a consultas do Prometheus.

• --loki-enforced-matchers: Correspondedores de rótulos LogQL aplicados com AND a todas as consultas nativas do Loki para restringir quais fluxos de log podem ser lidos (por exemplo, environment=~"prod|staging"). Requer --disable-api. Consulte aplicação de políticas a consultas do Loki.

• --loki-label-enumeration-fallback: O que as ferramentas de enumeração de rótulos fazem quando os correspondedores negativos impostos não conseguem restringi-las: reject (padrão) ou unfiltered. Consulte aplicação de políticas a consultas do Loki.

• --dashboard-schema: Defina como v2 para que update_dashboard rejeite um corpo clássico v1 (panels[]) que criaria um novo painel quando o Grafana disponibilizar o esquema de painel v2; o erro inclui um corpo v2 mínimo para tentar novamente. Os painéis v1 existentes continuam editáveis, e uma instância do Grafana sem v2 não é afetada. Padrão: vazio (sem alterações). Alternativa de ambiente: GRAFANA_DASHBOARD_SCHEMA.

• --disable-search: Desativa as ferramentas de pesquisa

• --disable-datasource: Desativa as ferramentas de fontes de dados

• --disable-incident: Desativa as ferramentas de incidentes

• --disable-prometheus: Desativa as ferramentas do Prometheus

• --disable-write: Desativa as ferramentas de gravação (operações de criação/atualização)

• --disable-query: Desativa as ferramentas de consulta (ferramentas que executam uma consulta em uma fonte de dados); as ferramentas de metadados e descoberta continuam disponíveis

• --enable-query: Mantém as ferramentas de consulta SQL bruta (query_sql, query_influxdb) registradas mesmo com --disable-write, e mantém query_datasource, uma fonte de render_grafana_app, disponível. Para as ferramentas de SQL bruta, equivale a --enable-write-tools=query_sql,query_influxdb; é mantido como atalho para esse caso comum.

• --enable-write-tools: Lista separada por vírgulas de nomes de ferramentas individuais a manter registrados mesmo com --disable-write, para ferramentas cujo comportamento de gravação tenha escopo suficientemente restrito para permitir a reativação independente. Não tem efeito sobre uma ferramenta cuja categoria inteira esteja desativada. Por exemplo, --enable-write-tools=generate_deeplink mantém o encurtamento de URLs (shorten=true) funcionando com --disable-write, e --enable-write-tools=alerting_rules_write permite alterações nas regras de alerta sem habilitar outras ferramentas de gravação.

• --disable-loki: Desativa as ferramentas do Loki

• --disable-elasticsearch: Desativa as ferramentas do Elasticsearch e do OpenSearch

• --disable-quickwit: Desativa as ferramentas do Quickwit

• --disable-influxdb: Desativa as ferramentas do InfluxDB

• --disable-alerting: Desativa as ferramentas de alertas

• --disable-dashboard: Desativa as ferramentas de painéis

• --disable-oncall: Desativa as ferramentas do OnCall

• --disable-asserts: Desativa as ferramentas do Asserts

• --disable-admin: Desativa as ferramentas de administração

• --disable-pyroscope: Desativa as ferramentas do Pyroscope

• --disable-navigation: Desativa as ferramentas de navegação

• --disable-rendering: Desativa as ferramentas de renderização (exportação de imagens de painéis)

• --disable-snapshot: Desativa as ferramentas de instantâneos

• --disable-cloudwatch: Desativa as ferramentas do CloudWatch

• --disable-cloudlogging: Desativa as ferramentas do Google Cloud Logging

• --disable-examples: Desativa as ferramentas de exemplos de consultas

• --disable-sql: Desativa as ferramentas de fontes de dados SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery). Os aliases --disable-clickhouse, --disable-snowflake, --disable-athena também funcionam.

• --disable-runpanelquery: Desativa as ferramentas de execução de consultas de painéis

• --disable-graphite: Desativa as ferramentas do Graphite

• --disable-dsquery: Desativa a fonte query_datasource de render_grafana_app

• --disable-provisioning: Desativa as ferramentas de provisionamento

• --disable-agento11y: Desativa as ferramentas do Agent Observability

• --disable-assistant: Desativa as ferramentas do Grafana Assistant

• --disable-docs: Desativa as ferramentas de documentação

Modo somente leitura

A opção --disable-write permite executar o servidor MCP em modo somente leitura, impedindo qualquer operação de gravação na sua instância do Grafana. Isso é útil em situações como:

• Usar contas de serviço com permissões limitadas de somente leitura
• Fornecer dados de observabilidade a assistentes de IA sem permitir modificações
• Executar em ambientes de produção nos quais o acesso de gravação deve ser restrito
• Cenários de teste e desenvolvimento nos quais você deseja evitar modificações acidentais

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

Ferramentas de painéis:

• update_dashboard

Ferramentas de pastas:

• create_folder

Ferramentas de incidentes:

• create_incident
• add_activity_to_incident
• update_incident

Ferramentas de alertas:

• alerting_rules_write (operações de criação, atualização e exclusão)
• alerting_silences_write (operações de criação, atualização e exclusão)
• alerting_routing_write (operação create_contact_point)

Cada ferramenta de gravação de alertas pode ser mantida individualmente com --enable-write-tools=<name>.

Ferramentas do OnCall:

• update_alert_group

Ferramentas de anotações:

• create_annotation
• update_annotation
• delete_annotation

Ferramentas de instantâneos:

• create_snapshot
• delete_snapshot

Ferramentas de navegação:

• generate_deeplink (shorten=true é ignorado e a URL completa é retornada; passe --enable-write-tools=generate_deeplink para manter o encurtamento de URLs)

Ferramentas de consulta SQL bruta:

Elas executam qualquer consulta fornecida sem inspecioná-la, portanto podem gravar quando as credenciais da fonte de dados permitem — query_sql executará um DROP TABLE, e query_influxdb executará um DELETE. Por isso, o modo somente leitura as remove. Passe --enable-query para mantê-las quando souber que as credenciais da fonte de dados são somente leitura.

• query_sql
• query_influxdb

Ferramentas do Agent Observability:

• agento11y_manage_evaluators (operações de upsert, exclusão, bifurcação e teste de avaliadores)
• agento11y_manage_eval_rules (operações de criação, atualização, exclusão e pré-visualização de regras e proteções)
• agento11y_manage_eval_collections (salvar e excluir conversas salvas; criar, atualizar e excluir coleções; adicionar e remover membros de coleções)
• agento11y_manage_experiments (operações de atualização e cancelamento de experimentos)
• agento11y_manage_test_suites (criar e atualizar conjuntos de testes; criar e publicar versões; fazer upsert e excluir casos de teste)

Todas as operações de leitura continuam disponíveis, permitindo consultar painéis, executar consultas PromQL/LogQL, listar recursos e recuperar dados. As linguagens de consulta que não permitem expressar uma gravação — PromQL, LogQL, TraceQL, a DSL do Elasticsearch, Graphite e CloudWatch — mantêm suas ferramentas de consulta no modo somente leitura; somente as ferramentas de SQL bruta listadas acima são removidas.

Modo sem consultas

A flag --disable-query remove todas as ferramentas que executam uma consulta em uma fonte de dados, mantendo as ferramentas de metadados e descoberta. Isso é útil quando você quer um assistente que possa explorar o que existe — fontes de dados, 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 tem datasources:query.

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

Flags	Ferramentas de consulta seguras (query_prometheus, query_loki_logs, run_panel_query, …)	Ferramentas de consulta com SQL bruto (query_sql, query_influxdb)
(nenhuma)	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á habilitada, as seguintes ferramentas não são registradas:

Ferramentas do Prometheus:

• query_prometheus
• query_prometheus_histogram

Ferramentas de renderização:

• render_grafana_app

Ferramentas do Loki:

• query_loki_logs
• query_loki_patterns

query_loki_stats e analyze_loki_labels continuam registradas: ambas enviam um seletor à fonte de dados, mas leem o índice e retornam contagens de streams, chunks e bytes, em vez do conteúdo dos logs.

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 fontes de dados SQL (também removidas por --disable-write, veja acima):

• query_sql

Ferramentas do Graphite:

• query_graphite
• query_graphite_density

Ferramentas do CloudWatch:

• query_cloudwatch
• query_cloudwatch_logs

Ferramentas do Google Cloud Logging:

• query_cloud_logging

Ferramentas do Pyroscope:

• query_pyroscope

Ferramentas de execução de consultas de painéis:

• 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 correspondentes 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 — continuam 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 controla todas as rotas para uma fonte de dados. No modo somente leitura, grafana_api_request permite POST para /api/ds/query apenas quando as ferramentas de consulta estão habilitadas (mesmo controle das ferramentas de SQL bruto — bloqueado por --disable-write, a menos que --enable-query o substitua). get_panel_image, que renderiza um painel no servidor, não é afetada.

Configuração de TLS do cliente (para conexões com o 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 da CA TLS para verificação do servidor
• --tls-skip-verify: Ignorar a verificação do certificado TLS (inseguro)

Configuração de 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 tanto com instâncias locais do Grafana quanto com o Grafana Cloud. Para o 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.

1. Se estiver usando autenticação com token de conta de serviço, crie uma conta de serviço no Grafana com permissões suficientes para usar as ferramentas desejadas, gere um token de conta de serviço e copie-o para a área de transferência para usá-lo no arquivo de configuração. Consulte a documentação de contas de serviço do Grafana para saber como criar tokens de conta de serviço. Dica: se você não se sentir à vontade para configurar escopos RBAC granulares, uma opção mais simples (mas menos restritiva) é atribuir à conta de serviço a função integrada Editor. Isso concede amplo acesso de leitura e gravação, que abrange a maioria das operações do servidor MCP — use-a quando a conveniência for mais importante do que 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 GRAFANA_SERVICE_ACCOUNT_TOKEN. O nome antigo da variável continuará funcionando por compatibilidade com versões anteriores, mas exibirá avisos de obsolescência.

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

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

Isso é especialmente útil no Kubernetes, onde um Secret montado como volume é atualizado no local quando o Secret subjacente muda (normalmente em cerca de 1 minuto). Combinado com o cache de cliente por solicitação — indexado pelo valor do token —, um token rotacionado gera automaticamente um novo cliente, sem reiniciar o pod nem causar indisponibilidade:

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

Os espaços em branco ao redor do conteúdo do arquivo (incluindo uma quebra de linha final) são removidos. Se GRAFANA_SERVICE_ACCOUNT_TOKEN e GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE estiverem definidos, o token passado diretamente terá precedência.

Suporte a várias organizações

Você pode especificar com qual organização interagir usando uma destas opções:

• Variável de ambiente: defina GRAFANA_ORG_ID como o ID numérico da organização
• Cabeçalho HTTP: defina X-Grafana-Org-Id ao usar o transporte 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 define o cabeçalho X-Grafana-Org-Id em todas as solicitações ao Grafana, garantindo que as operações sejam realizadas 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 chamadas de ferramentas a diferentes organizações, inicie o servidor com a flag --dynamic-multi-org. Essa opção vem desativada por padrão.

Quando habilitada, cada ferramenta aceita um argumento opcional orgId que substitui a organização da conexão para aquela chamada (definindo o cabeçalho X-Grafana-Org-Id e, para APIs da plataforma de aplicativos, o namespace do Kubernetes resolvido). Além disso, as ferramentas de fontes de dados por proxy são descobertas em todas as organizações às quais a credencial tem acesso. Chamadas que omitem orgId usam a organização padrão da conexão.

Isso só funciona com credenciais que pertencem a mais de uma organização (por exemplo, um usuário ou uma identidade em nome de outra pessoa); um token de conta de serviço continua 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 solicitações à API do Grafana usando a variável de ambiente GRAFANA_EXTRA_HEADERS. O valor deve ser um objeto JSON que mapeie nomes de cabeçalho 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 encaminhar todas as solicitações que este servidor faz ao Grafana por meio de um proxy SOCKS5 usando a variável de ambiente GRAFANA_SOCKS5_PROXY. O proxy se aplica 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 somente para os transportes do Grafana, sem afetar outros servidores MCP nem sua sessão do shell. Quando não definido, o comportamento permanece inalterado.

A URL deve usar o esquema socks5:// ou socks5h:// (o Go os trata de forma idêntica: a resolução do nome do 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 causa um erro na inicialização. Se a criação de uma conexão por proxy falhar durante a execução, o servidor falhará de forma segura, em vez de enviar silenciosamente o tráfego do Grafana diretamente.

Encaminhamento de cabeçalhos do cliente (somente Streamable-HTTP)

Quando o servidor MCP é executado atrás de um gateway ou proxy reverso que gerencia o SSO (por exemplo, um AWS ALB com OIDC), o cookie de sessão de cada usuário precisa chegar ao Grafana para que ele possa associar a solicitação ao usuário autenticado. A variável de ambiente GRAFANA_FORWARD_HEADERS habilita esse recurso especificando uma lista de permissões, separada por vírgulas, com os nomes dos cabeçalhos a serem copiados da solicitação HTTP recebida para todas as solicitações de saída à API do Grafana.

Isso se aplica somente ao usar o transporte streamable-http (-t streamable-http). Não tem efeito nos modos stdio ou SSE.

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

Os cabeçalhos encaminhados são mesclados com os cabeçalhos definidos em GRAFANA_EXTRA_HEADERS. Se um nome de cabeçalho aparecer em ambos, o valor da solicitação recebida terá precedência naquela solicitação.

Os cabeçalhos de contexto de rastreamento (traceparent, tracestate, baggage) são uma exceção: o próprio servidor propaga o contexto de rastreamento, portanto, um valor encaminhado nunca substitui o valor que ele injeta. Consulte observabilidade.

2. Há várias opções para instalar mcp-grafana:

   • uvx (recomendado): se você tiver o uv instalado, não será necessária nenhuma configuração adicional — uvx baixará e executará o servidor automaticamente:

     uvx mcp-grafana
     

   • Imagem Docker: use a imagem Docker pré-compilada do Docker Hub.

     Importante: o ponto de entrada da imagem Docker está configurado para executar o servidor MCP no modo SSE por padrão, mas a maioria dos usuários deve usar o modo STDIO para integração direta com assistentes de IA, como o Claude Desktop:

     1. Modo STDIO: para usar 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
     

     Observação — proteja os modos de rede: nos modos SSE e streamable-http, o contêiner se vincula a um endereço que não é de 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 se recusará a iniciar em uma versão principal futura). Defina MCP_GRAFANA_SERVER_TOKEN para exigir um Authorization: Bearer <token> dos clientes (recomendado). O modo STDIO não é afetado. Consulte Autenticação do chamador.

     2. Modo SSE: nesse modo, o servidor é executado 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
     

     3. Modo HTTP streamable: nesse modo, o servidor funciona como um processo independente que pode lidar com várias conexões de clientes. Você deve expor a porta 8000 usando a flag -p. Para esse 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 o modo HTTP streamable com HTTPS e 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 o binário: baixe a versão mais recente de mcp-grafana na página de versões e coloque-a no seu $PATH.

   • Compilar a partir do código-fonte: se você tiver o toolchain do Go instalado, também poderá 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. Esse diretório também deve estar no seu $PATH.

     GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest
     

   • Implantar no Kubernetes usando Helm: use o gráfico Helm 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
     

3. Adicione a configuração do servidor ao 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"
         }
       }
     }
   }
   

Observação: se você vir Error: spawn mcp-grafana ENOENT no Claude Desktop, será necessário 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"
      }
    }
  }
}

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

Usando o VSCode com servidor MCP remoto

Se você estiver usando o VSCode e executando o servidor MCP no 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 o modo HTTPS streamable HTTP 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á registros detalhados das solicitações e respostas HTTP entre o servidor MCP e a API do Grafana, o que pode ser útil para solucionar 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>"
      }
    }
  }
}

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

Configuração de TLS

Se sua instância do Grafana estiver atrás de mTLS ou exigir certificados TLS personalizados, você poderá configurar o servidor MCP para usar certificados personalizados. O servidor oferece suporte às seguintes opções de configuração de 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 da CA TLS para verificação do servidor
• --tls-skip-verify: ignorar a verificação do certificado TLS (inseguro; use apenas para testes)

Exemplo com autenticação por 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 de TLS é aplicada a todos os clientes HTTP usados pelo servidor MCP, incluindo:

• O cliente principal da OpenAPI do Grafana
• Clientes de datasource do Prometheus
• Clientes de datasource do Loki
• Clientes de gerenciamento de incidentes
• Clientes de alertas
• Clientes do Asserts

Exemplos de uso direto da CLI:

Para testar com certificados autoassinados:

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

Com autenticação por 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

Somente com certificado de CA personalizado:

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

Uso programático:

Se você estiver usando esta biblioteca programaticamente, também poderá criar funções de contexto com TLS habilitado:

// 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), valide previamente as URLs para evitar um panic que possa ser acionado:

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

Configuração de TLS do servidor (somente transporte Streamable HTTP)

Ao usar o transporte Streamable HTTP (-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 oferece suporte às seguintes opções de configuração de TLS para o transporte Streamable HTTP:

• --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)

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

Exemplo com servidor HTTPS Streamable HTTP:

./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 se conectariam então a https://localhost:8443/ em vez de http://localhost:8000/.

Exemplo com Docker e 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 integridade

Ao usar os transportes SSE (-t sse) ou Streamable HTTP (-t streamable-http), o servidor MCP expõe um endpoint de verificação de integridade em /healthz. Esse endpoint pode ser usado por balanceadores de carga, sistemas de monitoramento ou plataformas de orquestração para verificar se o servidor está em execução 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

Observação: o endpoint de verificação de integridade só está disponível ao usar os transportes SSE ou Streamable HTTP. Ele não está disponível ao usar o transporte stdio (-t stdio), pois o stdio não expõe um servidor HTTP.

Estatísticas anônimas de uso

O servidor pode enviar ao Grafana Labs estatísticas anônimas sobre seu uso: quais ferramentas foram chamadas, quantas dessas chamadas falharam e como o servidor está configurado. Cada relatório abrange um processo do servidor — não um usuário nem uma conversa — e é enviado a cada 4h e também uma vez no encerramento. O envio de relatórios está ativado por padrão. Para desativá-lo, defina --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled ou DO_NOT_TRACK=1.

Argumentos de ferramentas, nomes de recursos, consultas, linhas de log, mensagens de erro e credenciais nunca são enviados. As flags são registradas apenas pelo nome, nunca pelo valor, e a instância do Grafana é descrita apenas como cloud ou self_hosted — nunca por URL, nome de host, slug de stack ou organização. Nada é associado a um usuário, sessão ou cliente: não há identificador de sessão transmitido e não há como 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 desativa o envio de relatórios, seguindo a convenção DO_NOT_TRACK entre ferramentas. Somente 1 tem efeito, ele só pode desativar o envio, e tanto --usage-stats quanto GRAFANA_USAGE_STATS o substituem; assim, um host que o define globalmente ainda pode reativar o envio para um servidor específico.

GRAFANA_USAGE_STATS_ENDPOINT altera o destino. Não é uma opção para desativar o envio.

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

Observabilidade

O servidor MCP oferece suporte a métricas do Prometheus, rastreamento distribuído do OpenTelemetry e exportação de logs do OpenTelemetry, seguindo as convenções semânticas do 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.

Observação: atualmente, o mcp-grafana oferece suporte apenas ao transporte OTLP/gRPC para traces e logs. OTEL_EXPORTER_OTLP_PROTOCOL (e suas variantes _TRACES_PROTOCOL / _LOGS_PROTOCOL) não são respeitadas — o gRPC é usado independentemente disso.

Métricas

Ao usar os transportes SSE ou Streamable HTTP, ative as métricas do 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 (rótulos: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
http_server_request_duration_seconds	Histograma	Duração das solicitações do servidor HTTP (de otelhttp)

Observação: as métricas só estão disponíveis ao usar os transportes SSE ou Streamable HTTP. Elas não estão disponíveis com o transporte stdio.

Quando a proteção de custos do Loki (--loki-guardrail-mode) está ativada, mais quatro contadores registram suas decisões:

Métrica	Tipo	Descrição
mcp_loki_guardrail_admitted_total	Contador	Consultas que passaram por todas as verificações ativadas (rótulos: backend)
mcp_loki_guardrail_would_block_total	Contador	Consultas que falharam em uma verificação no modo shadow e foram executadas mesmo assim (rótulos: backend, reason)
mcp_loki_guardrail_blocked_total	Contador	Consultas rejeitadas no modo enforce (rótulos: backend, reason)
mcp_loki_guardrail_fail_open_total	Contador	Consultas que a proteção não conseguiu avaliar e permitiu (rótulos: 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 é contabilizada uma única vez, com o rótulo da primeira verificação executada (selector, depois range, depois bytes), de modo que os quatro contadores abrangem toda a população protegida. Consulte Observabilidade para saber como interpretá-los durante uma implantação de shadow → enforce.

Quando a proteção do Prometheus (--prometheus-guardrail-mode) está ativada, quatro contadores registram suas decisões da mesma forma:

Métrica	Tipo	Descrição
mcp_prometheus_guardrail_admitted_total	Contador	Consultas que passaram por todas as verificações ativadas
mcp_prometheus_guardrail_would_block_total	Contador	Consultas que falharam em uma verificação no modo shadow e foram executadas mesmo assim (rótulos: reason)
mcp_prometheus_guardrail_blocked_total	Contador	Consultas rejeitadas no modo enforce (rótulos: reason)
mcp_prometheus_guardrail_fail_open_total	Contador	Consultas permitidas com uma avaliação ativada indisponível (rótulos: reason)

reason é selector, range, points ou cardinality em would_block e blocked, contabilizado uma única vez sob a primeira verificação que falhou nessa ordem. fail_open usa unparseable ou cardinality_unknown. A política de cardinalidade opcional usa estatísticas TSDB em cache dos principais valores para exigir escopo explícito em métricas conhecidas de alta cardinalidade; ela não estima as séries selecionadas nem comprova que métricas ausentes são seguras. Endpoints TSDB sem suporte fazem essa política permitir a consulta. Não há rótulo backend.

Quem incorpora a biblioteca deve definir GrafanaConfig.MeterProvider (a contraparte de métricas de GrafanaConfig.Logger): a proteção é executada dentro de um manipulador de ferramenta, portanto não tem uma opção de construtor, e um processo que instala um MeterProvider global sem operações faria com que todos os registros fossem descartados.

Registro de solicitações lentas

A flag --slow-request-threshold emite um evento de log estruturado sempre que uma solicitação MCP (invocação de ferramenta, listagem, leitura de recurso etc.) excede a duração especificada. Ela é útil para diagnosticar consultas e chamadas de ferramentas lentas sem gerar uma quantidade excessiva de logs de depuração completos.

# 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 contém estes atributos estruturados:

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

O registro de solicitações lentas funciona em todos os transportes (incluindo stdio) e não requer --metrics. O limite padrão de 0 o desativa completamente. As ferramentas encaminhadas passam por tools/call e são incluídas 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 a variável específica do sinal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) está definida, 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 ferramentas 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 oferece suporte à propagação de contexto de trace W3C a partir do campo _meta das solicitações de chamada de ferramenta.

Logs

Quando OTEL_EXPORTER_OTLP_ENDPOINT (ou a variável específica do sinal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) está definida, o servidor também exporta logs estruturados via OTLP/gRPC, além da saída de texto simples existente em stderr. A ponte otelslog anexa automaticamente trace_id e span_id do span ativo, permitindo correlacionar os registros de log com os traces que o servidor já emite. Os traces e os logs resolvem seus endpoints de forma independente, portanto os dois sinais podem ser habilitados separadamente: definir apenas OTEL_EXPORTER_OTLP_TRACES_ENDPOINT habilita o tracing sem exportação de logs; definir apenas OTEL_EXPORTER_OTLP_LOGS_ENDPOINT habilita a exportação de logs sem tracing; e o OTEL_EXPORTER_OTLP_ENDPOINT genérico habilita ambos.

Se você usar o OTEL_EXPORTER_OTLP_ENDPOINT genérico, mas quiser desabilitar a exportação de logs (por exemplo, se seu backend não oferecer suporte ao 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 de logs em stderr não muda quando o registro OTLP está habilitado; você pode continuar usando os logs do contêiner ou redirecionar 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 a 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 a autenticação por meio de OTEL_EXPORTER_OTLP_LOGS_HEADERS (ou OTEL_EXPORTER_OTLP_HEADERS), seguindo o exemplo de tracing acima. Um coletor OTel local é opcional — útil para distribuição, processamento em lotes ou roteamento para vários backends, mas não é obrigatório.

As variantes específicas do 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 respeitadas e substituem suas contrapartes genéricas OTEL_EXPORTER_OTLP_* — consulte a especificação do exportador OTel para ver a lista completa e as regras de precedência.

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

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

Exemplo de Docker com métricas, tracing 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 políticas a consultas Prometheus

--prometheus-enforced-matchers permite que um operador restrinja quais séries do Prometheus as ferramentas nativas do Prometheus podem ler, adicionando, com AND, um conjunto fixo de seletores de rótulos PromQL a cada seletor de vetor em cada consulta nativa do Prometheus emitida pelo servidor. Isso é útil quando uma fonte de dados contém séries que não devem ser expostas (por exemplo, métricas com rótulos sensíveis de locatário ou cliente), mas não é possível restringir o acesso na camada do Prometheus.

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

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

Como funciona:

• Os seletores são analisados uma vez na inicialização (uma entrada inválida interrompe a inicialização do servidor) e adicionados a cada seletor de vetor em cada consulta. Uma consulta do usuário só pode restringir os resultados dentro dos limites impostos — nunca ampliá-los.
• Abrange query_prometheus, query_prometheus_histogram e painéis do Prometheus em run_panel_query.
• A descoberta nativa do Prometheus por meio de list_prometheus_label_names, list_prometheus_label_values e list_prometheus_metric_names também aplica os seletores a cada seletor de série, inclusive quando nenhum seletor é fornecido.
• list_prometheus_metric_metadata é recusado enquanto a aplicação de políticas estiver habilitada: o endpoint de metadados do Prometheus não pode filtrar por rótulos de série e combina metadados entre destinos. A descoberta do Cloud Monitoring também é recusada porque suas APIs de descoberta não podem aplicar a política completa de seletores do Prometheus.
• A política falha de forma segura: qualquer consulta que não possa ser analisada é rejeitada, em vez de ser enviada sem filtros.

[!IMPORTANT] Outras ferramentas habilitadas podem contornar esses seletores. Desabilite grafana_api_request com --disable-api, as ferramentas de renderização com --disable-rendering e o Grafana Assistant com --disable-assistant (ou --disable-write). Em particular, render_grafana_app pode enviar consultas Prometheus sem filtros por meio de sua fonte query_datasource. --disable-dsquery fecha essa fonte, mas não desabilita a renderização de painéis no servidor. Os snapshots de dashboards existentes também podem conter dados sem restrições; use --disable-snapshot quando isso for relevante.

Aplicação de políticas a consultas Loki

--loki-enforced-matchers permite que um operador restrinja quais fluxos de logs do Loki o servidor pode ler, adicionando, com AND, um conjunto fixo de seletores de rótulos LogQL a cada consulta nativa do Loki emitida pelo servidor. Isso é útil quando uma fonte de dados contém fluxos que não devem ser expostos (por exemplo, logs que podem conter informações sensíveis), mas não é possível restringir o acesso na camada do Grafana ou do Loki (o OSS não tem controle de acesso a rótulos por fonte de dados 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:

• Os seletores são analisados uma vez na inicialização (uma entrada inválida interrompe a inicialização do servidor) e adicionados a cada seletor de fluxo em cada consulta. Como o Loki combina seletores com AND dentro de um seletor, uma consulta do usuário só pode restringir os resultados dentro dos limites impostos — nunca ampliá-los. Um seletor do usuário que entre em conflito com a política (por exemplo, solicitando {namespace="vault"} sob uma exclusão) simplesmente não retorna resultados.
• Abrange query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names e list_loki_label_values.
• A política falha de forma segura: qualquer consulta que não possa ser analisada é rejeitada, em vez de ser enviada sem filtros.
• As fontes de dados VictoriaLogs usam LogsQL, que não pode ser reescrito com segurança; por isso, são totalmente recusadas enquanto a aplicação de políticas estiver habilitada.
• Seletores exclusivamente negativos não podem restringir os endpoints de enumeração de rótulos (o Loki rejeita um seletor independente sem um seletor positivo). Controle esse caso extremo com --loki-label-enumeration-fallback (reject por padrão, ou unfiltered para permitir a enumeração sem restrições de metadados de rótulos — as linhas de log nunca são expostas). Seletores positivos/de lista de permissões não são afetados.

[!IMPORTANT] A aplicação de políticas se limita às ferramentas de consulta do Loki. Outras ferramentas podem acessar os dados de log do Loki por caminhos que não passam pelo backend sujeito à política; portanto, para que a restrição seja efetiva, você também precisa desabilitá-las:

• --disable-api — grafana_api_request pode consultar diretamente o proxy da fonte de dados Loki (contorno completo).
• --disable-rendering — get_panel_image renderiza painéis Loki no servidor, gerando imagens com linhas de log sem restrições.
• --disable-assistant — ask_assistant delega ao Grafana Assistant, que lê dados do Loki no servidor em todos os fluxos. Só é registrado quando as ferramentas de escrita estão habilitadas; portanto, --disable-write também o desabilita.

O servidor registra um aviso na inicialização indicando quais dessas ferramentas ainda estão habilitadas. run_panel_query é seguro (reutiliza o caminho de consulta sujeito à política). As ferramentas do Tempo consultam traces, não logs do Loki, portanto não são um meio de contorno. Snapshots de dashboards (--disable-snapshot) também podem incorporar dados de painéis de logs capturados fora da aplicação da política.

Solução de problemas

Compatibilidade com versões do Grafana

Se você encontrar o seguinte erro ao usar ferramentas relacionadas a fontes de dados:

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

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

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

Desenvolvimento

Contribuições são bem-vindas! Leia CONTRIBUTING.md primeiro — o documento explica o que pertence a este servidor e como propor alterações.

Se você estiver adicionando uma nova ferramenta, abra uma proposta de ferramenta antes de escrever o código. Cada ferramenta habilitada por padrão é enviada ao modelo em todas as solicitações de todos os usuários; por isso, preferimos discutir a ideia a recusar uma solicitação de pull request já concluída. Correções de bugs, documentação, testes e novos parâmetros para ferramentas existentes não precisam de proposta — basta enviar uma PR.

Este projeto é escrito em Go. As versões das ferramentas e as tarefas de desenvolvimento ficam em mise.toml: instale mise, execute mise install para obter as ferramentas fixadas e mise tasks para listar as tarefas.

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

mise run 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 ponto de entrada dessa imagem personalizada usa o modo SSE por padrão. Para criar a imagem, use:

mise run 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 precisar executá-la no modo STDIO, substitua a configuração de transporte:

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

Testes

Há três tipos de testes disponíveis:

1. Testes unitários (não exigem dependências externas):

mise run test-unit

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

mise run test

2. Testes de integração (exigem que os contêineres Docker estejam em execução):

mise run test-integration

3. Testes de nuvem (exigem uma instância do Grafana na nuvem e credenciais):

mise run test-cloud

Observação: os testes de nuvem são configurados automaticamente na CI. Para desenvolvimento local, você precisará configurar sua própria instância do Grafana Cloud e obter as credenciais.

Testes de integração mais abrangentes exigem que uma instância do Grafana esteja em execução localmente na porta 3000; você pode iniciá-la com o Docker Compose:

docker-compose up -d

Se você adicionar mais ferramentas, inclua testes de integração para elas. Os testes existentes são um bom ponto de partida.

Lint

Para executar o lint no código, use:

mise run lint

Isso inclui um linter personalizado que verifica vírgulas sem escape nas tags de struct jsonschema. As vírgulas nos campos description precisam ser escapadas com \\, para evitar truncamento silencioso. Você pode executar apenas esse linter com:

mise run lint-jsonschema

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

Licença

Este projeto está licenciado sob a Licença Apache, Versão 2.0.