Grafana

oficial

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

GitHub
3.4k

O que você pode fazer com Grafana MCP?

  • Pesquisar e inspecionar dashboards — Use search_dashboards e get_dashboard_summary para encontrar dashboards e obter visões gerais compactas sem o JSON completo.
  • Consultar Prometheus e Loki — Execute consultas PromQL e LogQL em seus datasources, incluindo metadados e percentis de histograma.
  • Gerenciar alertas — Liste, crie, atualize e exclua regras de alerta, além de visualizar políticas de notificação e pontos de contato.
  • Gerar deeplinks — Crie URLs precisas para dashboards, painéis e Explore com intervalos de tempo usando as ferramentas de navegação.
  • Executar consultas de painel — Execute a consulta de um painel do dashboard com intervalos de tempo e variáveis personalizados usando run_panel_query.

Documentação

Servidor MCP do Grafana

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Um servidor Model Context Protocol (MCP) para Grafana.

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

Início Rápido

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

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

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

Requisitos

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

Recursos

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

Dashboards

  • Buscar dashboards: Encontre dashboards por título ou outros metadados
  • Obter dashboard por UID: Recupere detalhes completos do dashboard usando seu identificador único. Aviso: Dashboards grandes podem consumir espaço significativo da janela de contexto.
  • Obter resumo do dashboard: Obtenha uma visão geral compacta de um dashboard, incluindo título, quantidade 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 (ex.: $.title, $.panels[*].title) para buscar apenas os dados necessários e reduzir o consumo da janela de contexto
  • Atualizar ou criar um dashboard: Modifique dashboards existentes ou crie novos. Aviso: Requer o JSON completo do dashboard, que pode consumir grandes quantidades de espaço da janela de contexto.
  • Aplicar patch no dashboard: Aplique alterações específicas a um dashboard sem exigir o JSON completo, reduzindo significativamente o uso da janela de contexto para modificações direcionadas
  • Obter consultas dos painéis e informações do datasource: Obtenha o título, a string de consulta e as informações do datasource (incluindo UID e tipo, se disponível) de cada painel em um dashboard

Executar Consulta de Painel

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

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

Gerenciamento da Janela de Contexto

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

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

Datasources

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

Exemplos de Consulta

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

  • Obter exemplos de consulta: Recupere consultas de exemplo para diferentes tipos de datasource para aprender a sintaxe de consulta.

Consultas no Prometheus

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

Consultas no Loki

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

Consultas no InfluxDB

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

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

Consultas no ClickHouse

Nota: As ferramentas do ClickHouse estão desativadas por padrão. Para ativá-las, adicione clickhouse à sua flag --enabled-tools.

  • Listar tabelas do ClickHouse: Liste todas as tabelas em um banco de dados ClickHouse com contagens de linhas e tamanhos.
  • Descrever esquema da tabela: Obtenha nomes de colunas, tipos e metadados de uma tabela ClickHouse.
  • Consultar ClickHouse: Execute consultas SQL com suporte a macros do Grafana e substituição de variáveis.

Consultas no CloudWatch

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

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

Consultas no Graphite

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

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

Consultas no Athena

Nota: As ferramentas do Athena estão desativadas por padrão. Para ativá-las, adicione athena à sua flag --enabled-tools.

  • Listar catálogos do Athena: Descubra catálogos de dados disponíveis (ex.: AwsDataCatalog, conectores Iceberg).
  • Listar bancos de dados do Athena: Liste bancos de dados em um catálogo do Athena.
  • Listar tabelas do Athena: Liste tabelas em um banco de dados do Athena.
  • Descrever tabela do Athena: Obtenha nomes de colunas de uma tabela do Athena.
  • Consultar Athena: Execute consultas SQL no Amazon Athena via Grafana com substituição de macros, aplicação de limite e suporte a variáveis de template.

Consultas no Snowflake

Nota: As ferramentas do Snowflake estão desativadas por padrão. Para ativá-las, adicione snowflake à sua flag --enabled-tools.

As consultas passam pelo datasource Snowflake do Grafana (plugin Enterprise do Grafana grafana-snowflake-datasource), portanto a autenticação é tratada pela configuração do datasource no Grafana — as credenciais nunca são vistas pelo servidor MCP. Este é o mesmo modelo usado para as ferramentas do ClickHouse.

  • Listar tabelas do Snowflake: Descubra tabelas (com banco de dados, esquema, tipo, contagem de linhas e tamanho) via INFORMATION_SCHEMA.TABLES. Filtros opcionais de banco de dados/esquema.
  • Descrever esquema da tabela: Obtenha nomes de colunas, tipos de dados, anulabilidade, valores padrão e comentários de uma tabela do Snowflake.
  • Consultar Snowflake: Execute consultas SQL com suporte a substituição de macros e variáveis. Útil para consultar tabelas de eventos do Snowflake (ex.: SNOWFLAKE.TELEMETRY.EVENTS) para logs e traces, ou qualquer tabela de usuário.
    • Macros suportadas: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (ms Unix), $__interval (segundos), $__interval_ms e ${varname} para substituição de variáveis de template.

Consultas no Elasticsearch/OpenSearch

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

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

Consultas no Quickwit

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

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

Observabilidade de Agentes

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

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

Assistente Grafana

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

  • Pergunte ao assistente: Envie um prompt em linguagem natural para o Grafana Assistant e aguarde a resposta completa em texto. O assistente pode usar ferramentas, métricas, logs e outros contextos da stack — mais amplo do que disparar uma consulta isolada de fonte de dados. Passe o contextId retornado de volta em uma chamada de acompanhamento para continuar a mesma conversa. Tarefas complexas podem levar vários minutos; a chamada fica bloqueada até que a resposta seja concluída ou a solicitação expire (5 minutos).

Incidentes

  • Pesquisar, criar e atualizar incidentes: Gerencie incidentes no Grafana Incident, incluindo pesquisa, criação e adição de atividades aos incidentes.

Investigações Sift

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

Alertas

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

Grafana OnCall

  • Listar e gerenciar escalas: Visualize 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 em plantão atual: Veja quais usuários estão atualmente em plantão para uma escala.
  • Listar equipes e usuários: Visualize todas as equipes e usuários do OnCall.
  • Listar grupos de alertas: Visualize e filtre grupos de alertas do Grafana OnCall por vários critérios, incluindo estado, integração, labels e intervalo de tempo.
  • Obter detalhes do grupo de alertas: Recupere informações detalhadas sobre um grupo de alertas específico pelo seu ID.

Administração

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

  • Listar equipes: Visualize todas as equipes configuradas no Grafana.
  • Listar usuários: Visualize 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 da função: Obtenha detalhes de uma função específica do Grafana por 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 Grafana: Liste as permissões disponíveis e as capacidades de atribuição para um tipo de recurso.

Navegação

  • Gerar deeplinks: Crie URLs de deeplink precisas para recursos do Grafana em vez de depender de suposições de URL do LLM.
    • Links de dashboard: Gere links diretos para dashboards usando seu UID (por exemplo, http://localhost:3000/d/dashboard-uid)
    • Links de painel: 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?left={"datasource":"prometheus-uid"})
    • Suporte a intervalo de tempo: Adicione parâmetros de intervalo de tempo aos links (from=now-1h&to=now)
    • Parâmetros personalizados: Inclua parâmetros de consulta adicionais, como variáveis de dashboard ou intervalos de atualização

Anotações

  • Obter anotações: Consulte anotações com filtros. Suporta 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 Graphite: Crie anotações usando o formato Graphite (what, when, tags, data).
  • Atualizar anotação: Substitua todos os campos de uma anotação existente (atualização completa).
  • Corrigir anotação: Atualize apenas campos específicos de uma anotação (atualização parcial).
  • Obter tags de anotação: 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 opcionais 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 Grafana ou um dashboard completo como uma imagem PNG. Retorna a imagem como dados codificados em base64 para uso em relatórios, alertas ou apresentações. Suporta personalização de dimensões, intervalo de tempo, tema, escala e variáveis de dashboard. Também suporta a renderização de dashboards ainda não aplicados a partir de um branch de repositório de provisionamento (por exemplo, uma prévia de PR do git-sync) através do parâmetro opcional provisioningPreview.

Provisionamento

  • Listar repositórios de provisionamento: Liste os repositórios de provisionamento configurados para esta instância Grafana (por exemplo, fontes git-sync), retornando o slug de cada repositório junto com sua URL de origem, branch, caminho, estado de sincronização e saúde.
  • Validar arquivo de provisionamento: Aplique em modo de teste (dry-run) um arquivo de um repositório de provisionamento em um branch ou commit específico. Retorna se ele seria aceito, a ação do recurso (criar/atualizar), o tipo de recurso de destino e quaisquer erros de validação estruturados — a mesma superfície de admissão 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 determinada funcionalidade ou se não deseja ocupar muito espaço na janela de contexto. Para desabilitar uma categoria de ferramentas, use o 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 deeplinks de navegação, use --disable-navigation.

Permissões RBAC

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

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

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

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

Para mais informações sobre 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 requer 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 dashboards
    • folders:* - Acesso a todas as pastas
    • teams:* - Acesso a todas as equipes

  • Acesso limitado: Use UIDs ou IDs específicos para restringir o acesso a recursos individuais

    • datasources:uid:prometheus-uid - Acesso apenas a uma fonte de dados Prometheus específica
    • dashboards:uid:abc123 - Acesso apenas ao dashboard com UID abc123
    • folders:uid:xyz789 - Acesso apenas à pasta com UID xyz789
    • teams:id:5 - Acesso apenas à equipe com ID 5
    • global.users:id:123 - Acesso apenas ao usuário com ID 123

Exemplos:

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

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

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

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

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

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

Ferramentas

FerramentaCategoriaDescriçãoPermissões RBAC necessáriasEscopos necessários
list_teamsAdministraçãoListar todas as equipesteams:readteams:* ou teams:id:1
list_users_by_orgAdministraçãoListar todos os usuários em uma organizaçãousers:readglobal.users:* ou global.users:id:123
list_all_rolesAdministraçãoListar todos os papéis do Grafanaroles:readroles:*
get_role_detailsAdministraçãoObter detalhes de um papel do Grafanaroles:readroles:uid:editor
get_role_assignmentsAdministraçãoListar atribuições para um papelroles:readroles:uid:editor
list_user_rolesAdministraçãoListar papéis para usuáriosroles:readglobal.users:id:123
list_team_rolesAdministraçãoListar papéis para equipesroles:readteams:id:7
get_resource_permissionsAdministraçãoListar permissões para um recursopermissions:readdashboards:uid:abcd1234
get_resource_descriptionAdministraçãoDescrever um tipo de recurso do Grafanapermissions:readdashboards:*
search_dashboardsPesquisaPesquisar dashboardsdashboards:readdashboards:* ou dashboards:uid:abc123
get_dashboard_by_uidDashboardObter um dashboard por uiddashboards:readdashboards:uid:abc123
update_dashboardDashboardAtualizar ou criar um novo dashboarddashboards:create, dashboards:writedashboards:*, folders:* ou folders:uid:xyz789
get_dashboard_panel_queriesDashboardObter título do painel, consultas, UID da fonte de dados e tipo de um dashboarddashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Executar uma ou mais consultas de painel de um dashboarddashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyDashboardExtrair partes específicas de um dashboard usando expressões JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryDashboardObter um resumo compacto de um dashboard sem o JSON completodashboards:readdashboards:uid:abc123
list_datasourcesFontes de dadosListar fontes de dadosdatasources:readdatasources:*
get_datasourceFontes de dadosObter uma fonte de dados por UID ou nomedatasources:readdatasources:uid:prometheus-uid
get_query_examplesExamples*Obter consultas de exemplo para um tipo de fonte de dadosdatasources:readdatasources:*
query_prometheusPrometheusExecutar uma consulta contra uma fonte de dados Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusListar metadados de métricasdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusListar nomes de métricas disponíveisdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusListar nomes de rótulos que correspondem a um seletordatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusListar valores para um rótulo específicodatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusCalcular valores de percentil de histogramadatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidenteListar incidentes no Grafana IncidentPapel de visualizadorN/A
create_incidentIncidenteCriar um incidente no Grafana IncidentPapel de editorN/A
add_activity_to_incidentIncidenteAdicionar um item de atividade a um incidente no Grafana IncidentPapel de editorN/A
get_incidentIncidenteObter um único incidente por IDPapel de visualizadorN/A
query_loki_logsLokiConsultar e recuperar logs usando LogQL (consultas de log ou métricas)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiListar todos os nomes de rótulos disponíveis nos logsdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiListar valores para um rótulo de log específicodatasources:querydatasources:uid:loki-uid
query_loki_statsLokiObter estatísticas sobre fluxos de logdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiConsultar padrões de log detectados para identificar estruturas comunsdatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiAuditar uma estratégia de rótulos do Loki (ao vivo ou estática) e, opcionalmente, diagnosticar o desempenho de consultasdatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configConfiguraçãoGerar um snippet de Alloy loki.process que impõe rótulos aprovadosN/AN/A
query_influxdbInfluxDBConsultar InfluxDB usando InfluxQL (v1) ou Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Listar tabelas em um banco de dados ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Obter esquema de tabela com tipos de colunadatasources:querydatasources:uid:*
query_clickhouseClickHouse*Executar consultas SQL com substituição de macrodatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Listar namespaces disponíveis do AWS CloudWatchdatasources:querydatasources:uid:*
list_cloudwatch_metricsCloudWatch*Listar métricas em um namespacedatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Listar dimensões para uma métricadatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*Executar consultas de métricas do CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Listar catálogos de dados Athena disponíveisdatasources:querydatasources:uid:*
list_athena_databasesAthena*Listar bancos de dados em um catálogo Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Listar tabelas em um banco de dados Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Obter nomes de colunas para uma tabela Athenadatasources:querydatasources:uid:*
query_athenaAthena*Executar consultas SQL com substituição de macrodatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Consultar Elasticsearch ou OpenSearch usando sintaxe Lucene ou Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Consultar Quickwit usando sintaxe Lucene ou Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Listar tabelas em um banco de dados/esquema Snowflake via INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Obter esquema de tabela (tipos de coluna, anulabilidade, padrões, comentários)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Executar consultas SQL com substituição de macro/variáveldatasources:querydatasources:uid:*
alerting_manage_rulesAlertingGerenciar regras de alerta (listar, obter, versões, criar, atualizar, excluir)alert.rules:read + alert.rules:write para mutaçõesfolders:* or folders:uid:alerts-folder
alerting_manage_routingAlertingGerenciar políticas de notificação, pontos de contato e intervalos de tempoalert.notifications:readEscopo global
list_oncall_schedulesOnCallListar escalas do Grafana OnCallgrafana-oncall-app.schedules:readEscopos específicos do plugin
get_oncall_shiftOnCallObter detalhes de um turno OnCall específicografana-oncall-app.schedules:readEscopos específicos do plugin
get_current_oncall_usersOnCallObter usuários atualmente de plantão para uma escala específicagrafana-oncall-app.schedules:readEscopos específicos do plugin
list_oncall_teamsOnCallListar equipes do Grafana OnCallgrafana-oncall-app.user-settings:readEscopos específicos do plugin
list_oncall_usersOnCallListar usuários do Grafana OnCallgrafana-oncall-app.user-settings:readEscopos específicos do plugin
list_alert_groupsOnCallListar grupos de alerta do Grafana OnCall com opções de filtrografana-oncall-app.alert-groups:readEscopos específicos do plugin
get_alert_groupOnCallObter um grupo de alerta específico do Grafana OnCall pelo seu IDgrafana-oncall-app.alert-groups:readEscopos específicos do plugin
get_sift_investigationSiftRecuperar uma investigação Sift existente pelo seu UUIDFunção de visualizadorN/A
get_sift_analysisSiftRecuperar uma análise específica de uma investigação SiftFunção de visualizadorN/A
list_sift_investigationsSiftRecuperar uma lista de investigações Sift com um limite opcionalFunção de visualizadorN/A
find_error_pattern_logsSiftEncontra padrões de erro elevados em logs do Loki.Função de editorN/A
find_slow_requestsSiftEncontra solicitações lentas das fontes de dados tempo relevantes.Função de editorN/A
list_pyroscope_label_namesPyroscopeListar nomes de rótulos que correspondem a um seletordatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeListar valores de rótulos que correspondem a um seletor para um nome de rótulodatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeListar tipos de perfil disponíveisdatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeConsultar perfis, métricas ou ambos do Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsObter resumo de asserção para uma determinada entidadePermissões específicas do pluginEscopos específicos do plugin
agento11y_manage_conversationsAgent Observability*Listar, pesquisar e buscar conversas de LLM do Grafana Agent Observabilitygrafana-agento11y-app.conversations:readN/A
agento11y_manage_generationsAgent Observability*Buscar detalhes de geração de LLM e pontuações de avaliação do Grafana Agent Observabilitygrafana-agento11y-app.data:readN/A
agento11y_manage_agentsAgent Observability*Ler o catálogo de agentes: listar agentes, obter uma versão de agente completa, listar histórico de versões e agregados de pontuação por versãografana-agento11y-app.data:readN/A
agento11y_manage_evaluatorsAgent Observability*Gerenciar avaliadores, modelos de avaliador e o catálogo de juízes (listar, obter, upsert, bifurcar, testar, excluir)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write para mutações e testesN/A
agento11y_manage_eval_rulesAgent Observability*Gerenciar regras de avaliação e guardas (listar, obter, criar, atualizar, visualizar, excluir)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write para mutações e visualizaçõesN/A
agento11y_manage_eval_collectionsAgent Observability*Gerenciar conversas salvas e as coleções que as agrupam (listar, obter, salvar, criar, atualizar, excluir, adicionar e remover membros)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write para mutaçõesN/A
agento11y_manage_experimentsAgent Observability*Ler experimentos offline, suas tentativas, pontuações, metadados de artefatos e facetas de filtro; atualizar e cancelar um experimentografana-agento11y-app.data:read + grafana-agento11y-app.eval:write para mutaçõesN/A
agento11y_manage_test_suitesAgent Observability*Gerenciar as suítes de teste contra as quais os experimentos offline são executados, suas versões e seus casos de teste (listar, obter, criar, atualizar, rascunho, publicar, upsert, excluir)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write para mutaçõesN/A
ask_assistantAssistant*Enviar um prompt para o Grafana Assistant e retornar a resposta completa em texto (multi-turno via contextId)Permissões específicas do pluginEscopos específicos do plugin
generate_deeplinkNavigationGerar URLs de deeplink precisas para recursos do GrafanaNenhuma (geração de URL somente leitura)N/A
get_annotationsAnnotationsBuscar anotações com filtrosannotations:readannotations:* or annotations:id:123
create_annotationAnotaçõesCriar uma nova anotação (formato padrão ou Graphite)annotations:writeannotations:*
update_annotationAnotaçõesAtualizar campos específicos de uma anotação (atualização parcial)annotations:writeannotations:*
get_annotation_tagsAnotaçõesListar tags de anotações com filtragem opcionalannotations:readannotations:*
list_snapshotsSnapshotListar snapshots de painéis com filtros opcionais de consulta e limitedashboards:readdashboards:* or dashboards:uid:abc123
get_snapshotSnapshotObter metadados do snapshot e payload do painel pela chave do snapshotdashboards:readdashboards:* or dashboards:uid:abc123
create_snapshotSnapshotCriar um snapshot de painel a partir de um payload completo de paineldashboards:writedashboards:* or dashboards:uid:abc123
delete_snapshotSnapshotExcluir um snapshot de painel pela chave do snapshotdashboards:writedashboards:* or dashboards:uid:abc123
get_panel_imageRenderizaçãoRenderizar um painel ou painel armazenado — ou uma pré-visualização de provisionamento de uma branch do repositório — como uma imagem PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesProvisionamentoListar repositórios de provisionamento (ex.: fontes git-sync) com URL de origem, branch, estado de sincronização e saúdeprovisioning.repositories:readN/A
validate_provisioning_fileProvisionamentoAplicar em modo de simulação um arquivo de um repositório de provisionamento e relatar erros de validação de admissãoprovisioning.repositories:readN/A
* Desabilitado por padrão. Adicione a categoria a --enabled-tools para habilitar.

Referência de Flags da CLI

O binário mcp-grafana suporta 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: O host e a porta para o servidor SSE/streamable-http — padrão: localhost:8000
  • --base-path: Caminho base para o servidor SSE/streamable-http
  • --endpoint-path: Caminho do endpoint para o servidor streamable-http — padrão: /mcp
  • --server-name: Nome do servidor usado no handshake do MCP e no OTel service.name — padrão: mcp-grafana. Substitui a variável de ambiente GRAFANA_MCP_SERVER_NAME

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

A validação de Host/Origin é aplicada em todas as rotas do listener — /sse, /mcp, /healthz e /metrics — portanto, um navegador com DNS-rebinding não consegue alcançar nenhuma delas. O transporte Stdio não é afetado.

  • --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 (ex.: localhost:8000,127.0.0.1:8000,[::1]:8000). Um valor que seja interpretado como vazio (não definido, ,, ,, etc.) também usa os padrões, para que um erro de digitação não possa desabilitar silenciosamente a verificação. Requisições com um cabeçalho Host fora da lista de permissões são rejeitadas com 403. Passe * para desabilitar a verificação — só é seguro quando executado atrás de um proxy reverso confiável que reescreve Host, ou em uma rede isolada. Sondas httpGet do K8s e coletas externas de /metrics precisarão de um hostname explícito nesta lista, *, ou de uma sonda tcpSocket / uma porta de métricas separada (--metrics-address).
  • --allowed-origins: Lista de permissões separada por vírgulas de valores do cabeçalho Origin. Vazia por padrão — qualquer requisição que contenha um cabeçalho Origin é rejeitada (navegadores sempre enviam um para requisições cross-origin, e nenhum navegador deveria chamar este servidor diretamente). Defina uma lista explícita para permitir clientes baseados em navegador, ou * para desabilitar a verificação.

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

Opcionalmente, exige que clientes MCP se autentiquem no servidor. Isso é separado das credenciais que o servidor usa para acessar o Grafana. Stdio não é afetado.

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

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

Depuração e Registro:

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

Opções do Cliente Grafana:

  • --grafana-timeout: Limite de tempo para requisições feitas pelo cliente Grafana. Aceita strings de duração do Go (ex.: 10s, 500ms) — padrão: 10s
  • --include-args-in-spans: Inclui argumentos de chamada de ferramenta em spans do OpenTelemetry. Habilite apenas em ambientes de não 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 Prometheus em /metrics
  • --metrics-address: Endereço separado para o servidor de métricas (ex.: :9090). Se vazio, as métricas são servidas no servidor principal
  • --slow-request-threshold: Registra um evento quando qualquer requisição MCP (invocação de ferramenta, listagem, leitura de recurso, etc.) leva mais tempo que esta duração. Aceita strings de duração do Go (ex.: 500ms, 5s). O padrão 0 desativa o registro de requisições lentas. Veja a seção Registro de requisições lentas.
  • --slow-request-log-level: Nível de log para eventos de requisições lentas (info ou warn) — padrão: warn.

Gerenciamento de Sessão:

  • --session-idle-timeout-minutes: Tempo limite de inatividade da sessão em minutos. Sessões sem atividade por esta duração são encerradas automaticamente — padrão: 30. Defina como 0 para desabilitar o encerramento de sessões. Relevante apenas para transportes SSE e streamable-http.

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, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery e snowflake. Para habilitar categorias desabilitadas, adicione-as à lista (ex.: "search,datasource,...,snowflake")
  • --max-loki-log-limit: Número máximo de linhas de log retornadas por chamada de query_loki_logs — padrão: 100. Observação: defina este valor pelo menos 1 abaixo do max_entries_limit_per_query do lado do servidor Loki para permitir a detecção de truncamento (a ferramenta solicita limit+1 internamente para detectar se existem mais dados).
  • --disable-search: Desabilita ferramentas de busca
  • --disable-datasource: Desabilita ferramentas de datasource
  • --disable-incident: Desabilita ferramentas de incidentes
  • --disable-prometheus: Desabilita ferramentas Prometheus
  • --disable-write: Desabilita ferramentas de escrita (operações de criação/atualização)
  • --disable-loki: Desabilita ferramentas Loki
  • --disable-elasticsearch: Desabilita ferramentas Elasticsearch e OpenSearch
  • --disable-quickwit: Desabilita ferramentas Quickwit
  • --disable-influxdb: Desabilita ferramentas InfluxDB
  • --disable-alerting: Desabilita ferramentas de alertas
  • --disable-dashboard: Desabilita ferramentas de dashboard
  • --disable-oncall: Desabilita ferramentas oncall
  • --disable-asserts: Desabilita ferramentas asserts
  • --disable-sift: Desabilita ferramentas sift
  • --disable-admin: Desabilita ferramentas administrativas
  • --disable-pyroscope: Desabilita ferramentas pyroscope
  • --disable-navigation: Desabilita ferramentas de navegação
  • --disable-rendering: Desabilita ferramentas de renderização (exportação de imagem de painel/dashboard)
  • --disable-snapshot: Desabilita ferramentas de snapshot
  • --disable-cloudwatch: Desabilita ferramentas CloudWatch
  • --disable-examples: Desabilita ferramentas de exemplos de consulta
  • --disable-clickhouse: Desabilita ferramentas ClickHouse
  • --disable-snowflake: Desabilita ferramentas Snowflake
  • --disable-runpanelquery: Desabilita ferramentas de execução de consulta de painel
  • --disable-graphite: Desabilita ferramentas Graphite
  • --disable-athena: Desabilita ferramentas Athena
  • --disable-provisioning: Desabilita ferramentas de provisionamento
  • --disable-agento11y: Desabilita ferramentas de Observabilidade de Agente
  • --disable-assistant: Desabilita ferramentas do Assistente Grafana

Modo Somente Leitura

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

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

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

Ferramentas de Dashboard:

  • update_dashboard

Ferramentas de Pasta:

  • create_folder

Ferramentas de Incidentes:

  • create_incident
  • add_activity_to_incident

Ferramentas de Alertas:

  • alerting_manage_rules (operações de criação, atualização e exclusão)

Ferramentas de Anotações:

  • create_annotation
  • update_annotation

Ferramentas Sift:

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

Ferramentas de Snapshot:

  • create_snapshot
  • delete_snapshot

Ferramentas de Observabilidade de Agente:

  • agento11y_manage_evaluators (operações de upsert, exclusão, fork e teste de avaliador)
  • agento11y_manage_eval_rules (operações de criação, atualização, exclusão, pré-visualização de regra e guard)
  • agento11y_manage_eval_collections (salvar e excluir conversas salvas; criar, atualizar, excluir coleções; adicionar e remover membros de coleção)
  • agento11y_manage_experiments (operações de atualização e cancelamento de experimento)
  • agento11y_manage_test_suites (criar e atualizar suítes de teste; criar e publicar versões; upsert e excluir casos de teste)

Todas as operações de leitura permanecem disponíveis, permitindo consultar dashboards, executar consultas PromQL/LogQL, listar recursos e recuperar dados.

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

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

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

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

Uso

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

  1. Se estiver usando autenticação por token de conta de serviço, crie uma conta de serviço no Grafana com permissões suficientes para usar as ferramentas desejadas, gere um token de conta de serviço e copie-o para a área de transferência para uso no arquivo de configuração. Siga a documentação de contas de serviço do Grafana para detalhes sobre como criar tokens de conta de serviço. Dica: Se você não se sente confortável configurando escopos RBAC granulares, uma opção mais simples (porém menos restritiva) é atribuir o papel integrado Editor à conta de serviço. Isso concede acesso amplo de leitura/escrita que cobre a maioria das operações do servidor MCP — use-o quando a conveniência superar 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 o uso de GRAFANA_SERVICE_ACCOUNT_TOKEN. O nome antigo da variável continuará funcionando por compatibilidade reversa, mas exibirá avisos de depreciação.

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

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

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

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

O espaço em branco ao redor (incluindo uma nova linha final) é removido do conteúdo do arquivo. Se tanto GRAFANA_SERVICE_ACCOUNT_TOKEN quanto GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE estiverem definidos, o token inline tem precedência.

Suporte Multi-Organização

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

  • 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 transportes SSE ou HTTP streamable (o cabeçalho tem precedência sobre a variável de ambiente — ou seja, você também pode definir uma organização padrão).

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

Exemplo com ID de organização:

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

Cabeçalhos HTTP Personalizados

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

Exemplo com cabeçalhos personalizados:

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

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

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

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

Exemplo: encaminhar o cookie de sessão

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

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

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

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

  1. Você tem várias opções para instalar o mcp-grafana:

    • uvx (recomendado): Se você tiver uv instalado, nenhuma configuração extra é necessária — o uvx baixará e executará automaticamente o servidor:

      uvx mcp-grafana

    • Imagem Docker: Use a imagem Docker pré-construída do Docker Hub.

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

      1. Modo STDIO: Para o modo stdio, você deve substituir explicitamente o padrão com -t stdio e incluir o sinalizador -i para manter o stdin aberto:
      docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

      Nota — proteja os modos em rede: Nos modos SSE e streamable-http, o contêiner vincula um endereço não loopback (0.0.0.0:8000). Sem um token de chamador, o servidor inicia, mas registra um erro de segurança (no nível de log error, para que não seja ocultado por --log-level; e se recusará a iniciar em uma futura versão principal). Defina MCP_GRAFANA_SERVER_TOKEN para exigir um Authorization: Bearer <token> dos clientes (recomendado). O modo STDIO não é afetado. Consulte Autenticação do Chamador.

      1. Modo SSE: Neste modo, o servidor roda como um servidor HTTP ao qual os clientes se conectam. Você deve expor a porta 8000 usando o sinalizador -p:
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      1. Modo Streamable HTTP: Neste modo, o servidor opera como um processo independente que pode lidar com múltiplas conexões de clientes. Você deve expor a porta 8000 usando o sinalizador -p: Para este modo, você deve substituir explicitamente o padrão com -t streamable-http
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http

      Para o modo HTTPS streamable HTTP com certificados TLS do servidor:

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

    • Baixar binário: Baixe a versão mais recente do mcp-grafana na página de releases e coloque-o no seu $PATH.

    • Compilar a partir do código-fonte: Se você tiver um toolchain Go instalado, também pode compilar e instalá-lo a partir do código-fonte, usando a variável de ambiente GOBIN para especificar o diretório onde o binário deve ser instalado. Isso também deve estar no seu $PATH.

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/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

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

    Se usando uvx:

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

    Se usando o binário:

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

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

Se usando Docker:

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

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

Usando VSCode com servidor MCP remoto

Se você 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 o sinalizador -debug ao comando. Isso fornecerá registro detalhado 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 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 usando Docker:

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

Nota: 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 TLS

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

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

Exemplo com autenticação de certificado do cliente:

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

Exemplo com Docker:

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

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

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

Exemplos de Uso Direto via CLI:

Para testes com certificados autoassinados:

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

Com autenticação de certificado do cliente:

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

Somente com certificado CA personalizado:

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

Uso Programático:

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

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

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

Validação de URL:

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

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

Configuração TLS do Servidor (Somente Transporte 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 suporta as seguintes opções de configuração TLS para o transporte streamable HTTP:

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

Nota: Esses sinalizadores são completamente separados dos sinalizadores TLS do cliente documentados acima. Os sinalizadores TLS do cliente configuram como o servidor MCP se conecta ao Grafana, enquanto esses sinalizadores 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 então se conectariam a https://localhost:8443/ em vez de http://localhost:8000/.

Exemplo Docker com TLS do servidor:

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

Endpoint de Verificação de 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á rodando e aceitando conexões.

Endpoint: GET /healthz

Resposta:

  • Código de Status: 200 OK
  • Corpo: ok

Exemplo de uso:

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

# With custom address
curl http://localhost:9090/healthz

Nota: O endpoint de verificação de integridade está disponível apenas quando se usa os transportes SSE ou streamable HTTP. Não está disponível ao usar o transporte stdio (-t stdio), pois o stdio não expõe um servidor HTTP.

Observabilidade

O servidor MCP suporta 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 via variáveis de ambiente padrão OTEL_* e funcionam com qualquer transporte.

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

Métricas

Ao usar os transportes SSE ou streamable HTTP, habilite métricas do Prometheus com o sinalizador --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étricaTipoDescrição
mcp_server_operation_duration_secondsHistogramaDuração das operações MCP (rótulos: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramaDuração das sessões do cliente MCP (rótulos: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramaDuração das solicitações do servidor HTTP (do otelhttp)

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

Registro de solicitações lentas

O sinalizador --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 fornecida. É útil para diagnosticar consultas lentas e chamadas de ferramentas sem se afogar no log de depuração completo.

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

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

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

O evento de log carrega os seguintes atributos estruturados:

AtributoDescrição
mcp.methodO método MCP (por exemplo, tools/call, tools/list, resources/read)
durationDuração observada da solicitação
thresholdLimiar configurado
toolNome da ferramenta (presente apenas para métodos tools/call)
errorValor de erro, quando a solicitação falhou (contexto de melhor esforço; conteúdo controlado pelo encapsulamento de erro upstream)
error.typeClassificação de erro de cardinalidade limitada (_OTHER para erros não tipados)

O registro de solicitações lentas funciona em todos os transportes (incluindo stdio) e não requer --metrics. O limiar padrão de 0 o desativa completamente. Ferramentas de proxy passam por tools/call e são cobertas automaticamente.

Rastreamento

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

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

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

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

Logs

Quando OTEL_EXPORTER_OTLP_ENDPOINT (ou o específico de sinal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) é definido, 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, para que os registros de log se correlacionem com os rastreamentos que o servidor já emite.

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

Se você usar o genérico OTEL_EXPORTER_OTLP_ENDPOINT mas quiser desabilitar a exportação de logs (por exemplo, seu backend não suporta 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 log de stderr permanece inalterado quando o log OTLP está habilitado; você pode continuar contando com logs de contêiner ou redirecionar o stderr para /dev/null se preferir.

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

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

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

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

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

Exemplo com Docker incluindo métricas, rastreamento e logs:

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

Solução de problemas

Compatibilidade de 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 operações de fonte 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! Abra uma issue ou envie um pull request se tiver sugestões ou melhorias.

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

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

make run

Para executar o servidor localmente no modo SSE, use:

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

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

make build-image

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

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

Se precisar executá-la no modo STDIO, altere 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 de unidade (sem dependências externas):
make test-unit

Você também pode executar testes de unidade com:

make test
  1. Testes de integração (requerem contêineres docker em execução):
make test-integration
  1. Testes na nuvem (requerem uma instância do Grafana na nuvem e credenciais):
make test-cloud

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

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

docker-compose up -d

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

make test-all

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

Linting

Para executar o lint do código, use:

make lint

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

make lint-jsonschema

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

Licença

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