Grafana MCP Server

oficial

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

GitHub
3.2k

Documentação

Servidor MCP do Grafana

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Um servidor Model Context Protocol (MCP) para o 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 (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 o 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

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

Funcionalidades

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

Dashboards

  • Pesquisar 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 um espaço significativo da janela de contexto.
  • Obter resumo do dashboard: Obtenha uma visão geral compacta de um dashboard, incluindo título, contagem de painéis, tipos de painéis, variáveis e metadados, sem o JSON completo para minimizar o uso da janela de contexto
  • Obter propriedade do dashboard: Extraia partes específicas de um dashboard usando expressões JSONPath (ex.: $.title, $.panels[*].title) para buscar apenas os dados necessários e reduzir o consumo da janela de contexto
  • Atualizar ou criar um dashboard: Modifique dashboards existentes ou crie novos. Aviso: Requer o JSON completo do dashboard, o que pode consumir grandes quantidades de espaço da janela de contexto.
  • Aplicar patch no dashboard: Aplique alterações específicas a um dashboard sem exigir o JSON completo, reduzindo significativamente o uso da janela de contexto para modificações direcionadas
  • Obter consultas do painel e informações da fonte 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 em um dashboard

Executar Consulta do Painel

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

  • Executar consulta do 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 o uso da janela de contexto de forma eficaz (issue #101):

  • Use get_dashboard_summary para visão geral do dashboard e planejamento de 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 você precise especificamente do JSON completo do dashboard

Fontes de Dados

  • Listar e obter informações da fonte de dados: Visualize todas as fontes de dados configuradas e recupere informações detalhadas sobre cada uma.
    • Tipos de fonte de dados suportados: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Exemplos de Consulta

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

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

Consultas ao Prometheus

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

Consultas ao Loki

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

Consultas ao InfluxDB

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

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

Consultas ao ClickHouse

Nota: As ferramentas do ClickHouse estão desabilitadas por padrão. Para habilitá-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 para uma tabela do ClickHouse.
  • Consultar ClickHouse: Execute consultas SQL com suporte a macros do Grafana e substituição de variáveis.

Consultas ao CloudWatch

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

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

Consultas ao Graphite

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

  • Consultar Graphite: Execute consultas da API de renderização do Graphite em uma fonte de dados do 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 ao Athena

Nota: As ferramentas do Athena estão desabilitadas por padrão. Para habilitá-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 para uma tabela do Athena.
  • Consultar Athena: Execute consultas SQL no Amazon Athena via Grafana com substituição de macros, imposição de limites e suporte a variáveis de template.

Consultas ao Snowflake

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

As consultas passam pela fonte de dados Snowflake do Grafana (plugin Grafana Enterprise grafana-snowflake-datasource), então a autenticação é tratada pela configuração da fonte de dados 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, nulabilidade, padrões e comentários para uma tabela do Snowflake.
  • Consultar Snowflake: Execute consultas SQL com suporte a macros e substituição de variáveis. Útil para consultar tabelas de eventos do Snowflake (ex.: SNOWFLAKE.TELEMETRY.EVENTS) para logs e rastros, ou qualquer tabela de usuário.
    • Macros suportadas: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (segundos), $__interval_ms e ${varname} para substituição de variáveis de template.

Consultas ao Elasticsearch/OpenSearch

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

  • Consultar Elasticsearch/OpenSearch: Execute consultas de pesquisa em fontes de dados do Elasticsearch ou OpenSearch usando a 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 ao Quickwit

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

  • Consultar Quickwit: Execute consultas de pesquisa em fontes de dados do Quickwit usando a 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.

Incidentes

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

Investigações do Sift

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

Alertas

  • Listar e obter 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 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 roteamento de alertas: Visualize políticas de notificação, pontos de contato e intervalos de tempo. Suporta pontos de contato gerenciados pelo Grafana e receptores de fontes de dados externas do Alertmanager (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

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

Administração

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

  • Listar equipes: Visualize todas as equipes configuradas no Grafana.
  • Listar usuários: Visualize todos os usuários em uma organização no Grafana.
  • Listar todas as funções: Liste todas as funções do Grafana, com um filtro opcional para funções delegáveis.
  • Obter detalhes da função: Obtenha detalhes de uma função específica do Grafana pelo UID.
  • Listar atribuições para uma função: Liste todos os usuários, equipes e contas de serviço atribuídos a uma função.
  • Listar funções para usuários: Liste todas as funções atribuídas a um ou mais usuários.
  • Listar funções para equipes: Liste todas as funções atribuídas a uma ou mais equipes.
  • Listar permissões para um recurso: Liste todas as permissões definidas para um recurso específico (dashboard, fonte de dados, pasta, etc.).
  • Descrever um recurso do Grafana: Liste permissões disponíveis e 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 (ex., http://localhost:3000/d/dashboard-uid)
    • Links de painel: Crie links para painéis específicos dentro de dashboards com o parâmetro viewPanel (ex., http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Links do Explore: Gere links para o Grafana Explore com fontes de dados pré-configuradas (ex., 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 dashboard com filtros opcionais de consulta e limite.
  • Obter snapshot: Recupere 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 de 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 de dashboard do 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 de um branch de repositório de provisionamento (ex., uma prévia de PR de git-sync) por meio do parâmetro opcional provisioningPreview.

Provisionamento

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

A lista de ferramentas é configurável, para que você possa escolher quais ferramentas deseja disponibilizar para o cliente MCP. Isso é útil se você não usa determinada funcionalidade ou se não deseja ocupar muito 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 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, certifique-se de 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 (ex., 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 amplo acesso de leitura/gravação que permitirá a maioria das operações do servidor MCP; ela é menos granular (e, portanto, menos restritiva) do que escopos aplicados manualmente, portanto, use-a apenas quando a conveniência for mais importante do que o acesso estrito de privilégio mínimo.

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

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

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 requer a combinação apropriada 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 total 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_teamsAdminListar todas as equipesteams:readteams:* ou teams:id:1
list_users_by_orgAdminListar todos os usuários em uma organizaçãousers:readglobal.users:* ou global.users:id:123
list_all_rolesAdminListar todas as funções do Grafanaroles:readroles:*
get_role_detailsAdminObter detalhes de uma função do Grafanaroles:readroles:uid:editor
get_role_assignmentsAdminListar atribuições para uma funçãoroles:readroles:uid:editor
list_user_rolesAdminListar funções para usuáriosroles:readglobal.users:id:123
list_team_rolesAdminListar funções para equipesroles:readteams:id:7
get_resource_permissionsAdminListar permissões para um recursopermissions:readdashboards:uid:abcd1234
get_resource_descriptionAdminDescrever 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 e tipo da fonte de dados de um dashboarddashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Executar uma ou mais consultas de painel do 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_examplesExemplos*Obter consultas de exemplo para um tipo de fonte de dadosdatasources:readdatasources:*
query_prometheusPrometheusExecutar uma consulta em 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 IncidentFunção de VisualizadorN/A
create_incidentIncidenteCriar um incidente no Grafana IncidentFunção de EditorN/A
add_activity_to_incidentIncidenteAdicionar um item de atividade a um incidente no Grafana IncidentFunção de EditorN/A
get_incidentIncidenteObter um único incidente por IDFunção 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 da consultadatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configConfiguraçãoGerar um trecho do Alloy loki.process que impõe rótulos aprovadosN/AN/A
query_influxdbInfluxDBConsultar o 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 da tabela com tipos de colunadatasources:querydatasources:uid:*
query_clickhouseClickHouse*Executar consultas SQL com substituição de macrodatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Listar namespaces AWS CloudWatch disponíveisdatasources: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 disponíveis do Athenadatasources:querydatasources:uid:*
list_athena_databasesAthena*Listar bancos de dados em um catálogo do Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Listar tabelas em um banco de dados do Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Obter nomes de colunas para uma tabela do Athenadatasources:querydatasources:uid:*
query_athenaAthena*Executar consultas SQL com substituição de macrosdatasources: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 do Snowflake via INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Obter esquema da tabela (tipos de coluna, nulabilidade, padrões, comentários)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Executar consultas SQL com substituição de macros/variáveisdatasources:querydatasources:uid:*
alerting_manage_rulesAlertasGerenciar regras de alerta (listar, obter, versões, criar, atualizar, excluir)alert.rules:read + alert.rules:write para mutaçõesfolders:* ou folders:uid:alerts-folder
alerting_manage_routingAlertasGerenciar políticas de notificação, pontos de contato e intervalos de tempoalert.notifications:readEscopo global
list_oncall_schedulesOnCallListar agendas do Grafana OnCallgrafana-oncall-app.schedules:readEscopos específicos do plugin
get_oncall_shiftOnCallObter detalhes de um turno específico do OnCallgrafana-oncall-app.schedules:readEscopos específicos do plugin
get_current_oncall_usersOnCallObter usuários atualmente de plantão para uma agenda 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 alertas do Grafana OnCall com opções de filtrografana-oncall-app.alert-groups:readEscopos específicos do plugin
get_alert_groupOnCallObter um grupo de alertas específico do Grafana OnCall pelo seu IDgrafana-oncall-app.alert-groups:readEscopos específicos do plugin
get_sift_investigationSiftRecuperar uma investigação existente do Sift pelo seu UUIDFunção de VisualizadorN/A
get_sift_analysisSiftRecuperar uma análise específica de uma investigação do SiftFunção de VisualizadorN/A
list_sift_investigationsSiftRecuperar uma lista de investigações do Sift com um limite opcionalFunção de VisualizadorN/A
find_error_pattern_logsSiftEncontra padrões elevados de erro nos logs do Loki.Função de EditorN/A
find_slow_requestsSiftEncontra requisições lentas das fontes de dados relevantes do tempo.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
generate_deeplinkNavegaçãoGerar URLs de deep link precisas para recursos do GrafanaNenhuma (geração de URL somente leitura)N/A
get_annotationsAnotaçõesBuscar anotações com filtrosannotations:readannotations:* ou 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ção com filtragem opcionalannotations:readannotations:*
list_snapshotsSnapshotListar snapshots de dashboard com filtros opcionais de consulta e limitedashboards:readdashboards:* ou dashboards:uid:abc123
get_snapshotSnapshotObter metadados do snapshot e payload do dashboard pela chave do snapshotdashboards:readdashboards:* ou dashboards:uid:abc123
create_snapshotSnapshotCriar um snapshot de dashboard a partir de um payload completo do dashboarddashboards:writedashboards:* ou dashboards:uid:abc123
delete_snapshotSnapshotExcluir um snapshot de dashboard pela chave do snapshotdashboards:writedashboards:* ou dashboards:uid:abc123
get_panel_imageRenderizaçãoRenderizar um dashboard ou painel armazenado — ou uma prévia de provisionamento de um branch de repositório — como uma imagem PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesProvisionamentoListar repositórios de provisionamento (ex.: fontes git-sync) com sua URL de origem, branch, estado de sincronização e saúdeprovisioning.repositories:readN/A
validate_provisioning_fileProvisionamentoAplica um arquivo de um repositório de provisionamento em modo de simulação e relata 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 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: /

Depuração e Logging:

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

Observabilidade:

  • --metrics: Habilita o endpoint de métricas do 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.) demorar mais que esta duração. Aceita strings de duração do Go (ex.: 500ms, 5s). O padrão 0 desabilita o logging de requisições lentas. Veja a seção Logging de requisições lentas.
  • --slow-request-log-level: Nível de log para eventos de requisição lenta (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 automaticamente removidas - padrão: 30. Defina como 0 para desabilitar a remoção de sessões. Relevante apenas para os 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, 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 query_loki_logs - padrão: 100. Nota: 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 há mais dados).
  • --disable-search: Desabilita ferramentas de busca
  • --disable-datasource: Desabilita ferramentas de fonte de dados
  • --disable-incident: Desabilita ferramentas de incidentes
  • --disable-prometheus: Desabilita ferramentas do Prometheus
  • --disable-write: Desabilita ferramentas de escrita (operações de criação/atualização)
  • --disable-loki: Desabilita ferramentas do Loki
  • --disable-elasticsearch: Desabilita ferramentas do Elasticsearch e OpenSearch
  • --disable-quickwit: Desabilita ferramentas do Quickwit
  • --disable-influxdb: Desabilita ferramentas do InfluxDB
  • --disable-alerting: Desabilita ferramentas de alertas
  • --disable-dashboard: Desabilita ferramentas de dashboard
  • --disable-oncall: Desabilita ferramentas do OnCall
  • --disable-asserts: Desabilita ferramentas de asserts
  • --disable-sift: Desabilita ferramentas do Sift
  • --disable-admin: Desabilita ferramentas de administração
  • --disable-pyroscope: Desabilita ferramentas do 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 do CloudWatch
  • --disable-examples: Desabilita ferramentas de exemplos de consulta
  • --disable-clickhouse: Desabilita ferramentas do ClickHouse
  • --disable-snowflake: Desabilita ferramentas do Snowflake
  • --disable-runpanelquery: Desabilita ferramentas de execução de consulta de painel
  • --disable-graphite: Desabilita ferramentas do Graphite
  • --disable-athena: Desabilita ferramentas do Athena
  • --disable-provisioning: Desabilita ferramentas de provisionamento

Modo Somente Leitura

A flag --disable-write fornece uma maneira de executar o servidor MCP em modo somente leitura, prevenindo quaisquer operações de escrita na sua instância do Grafana. Isso é útil para cenários onde você deseja fornecer acesso seguro e somente leitura, como:

  • Usar contas de serviço com permissões limitadas de somente leitura
  • Fornecer a assistentes de IA dados de observabilidade sem capacidades de modificação
  • Executar em ambientes de produção onde o acesso de escrita deve ser restrito
  • Cenários de teste e desenvolvimento onde você deseja prevenir 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 criar, atualizar, excluir)

Ferramentas de Anotação:

  • create_annotation
  • update_annotation

Ferramentas do Sift:

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

Ferramentas de Snapshot:

  • create_snapshot
  • delete_snapshot

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 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 CA TLS para verificação do servidor
  • --tls-skip-verify: Ignorar a verificação do certificado TLS (inseguro)

Configuração TLS do Servidor (apenas 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 (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 conta de serviço do Grafana para obter detalhes sobre como criar tokens de conta de serviço. Dica: Se você não se sentir confortável configurando escopos RBAC refinados, uma opção mais simples (mas menos restritiva) é atribuir a função integrada Editor à conta de serviço. Isso concede acesso amplo de leitura/escrita que cobre a maioria das operações do servidor MCP — use quando a conveniência superar os requisitos estritos de privilégio mínimo.

    Nota: A variável de ambiente GRAFANA_API_KEY está obsoleta e será removida em uma versão futura. Por favor, migre para usar GRAFANA_SERVICE_ACCOUNT_TOKEN. O nome da variável antiga continuará funcionando para compatibilidade retroativa, 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, então tokens rotacionados são capturados 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 reinicialização do pod e sem tempo de inatividade:

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

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

Suporte a Múltiplas Organizações

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

  • Variável de ambiente: Defina GRAFANA_ORG_ID com o ID numérico da organização
  • Cabeçalho HTTP: Defina X-Grafana-Org-Id ao usar os transportes SSE ou HTTP streamable (o cabeçalho tem precedência sobre a variável de ambiente - o que significa que 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 para o Grafana, garantindo que as operações sejam realizadas dentro do 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ç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\"}"
      }
    }
  }
}

Encaminhando Cabeçalhos do Cliente (Apenas SSE/Streamable-HTTP)

Quando o servidor MCP é executado atrás de um gateway ou proxy reverso que lida com SSO (ex.: 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 requisição ao usuário autenticado. A variável de ambiente GRAFANA_FORWARD_HEADERS habilita isso especificando uma lista de permissões separada por vírgulas de nomes de cabeçalho para copiar da requisição HTTP de entrada para cada requisiçã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 requisição de entrada tem precedência para essa requisição.

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

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

      uvx mcp-grafana

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

      Importante: O 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 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 sobrescrever 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
      1. Modo SSE: Neste 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> grafana/mcp-grafana
      1. Modo HTTP Streamable: Neste modo, o servidor opera como um processo independente que pode lidar com múltiplas conexões de clientes. Você deve expor a porta 8000 usando a flag -p: Para este modo, você deve sobrescrever 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> 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> \
  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 da página de releases e coloque-o no seu $PATH.

    • Compilar a partir do código fonte: Se você tiver uma toolchain Go instalada, também pode compilar e instalar a partir do código fonte, usando a variável de ambiente GOBIN para especificar o diretório onde o binário deve ser instalado. Isso também deve estar 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 Helm chart do repositório grafana/helm-charts

      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 seu arquivo de configuração do cliente. Por exemplo, para o Claude Desktop:

    Se estiver usando uvx:

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

    Se estiver usando o binário:

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

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

Se estiver usando Docker:

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

Nota: O argumento -t stdio é essencial aqui porque sobrescreve 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 sobrescrever 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 HTTP streamable com HTTPS usando certificados TLS do servidor:

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

Modo Debug

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

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

Se estiver usando o binário:

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

Se estiver usando Docker:

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

Nota: Assim como na configuração padrão, o argumento -t stdio é necessário para sobrescrever 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 do certificado TLS (inseguro, use apenas para testes)

Exemplo com autenticação de certificado de 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 fonte de dados Prometheus
  • Clientes de fonte de dados Loki
  • Clientes de gerenciamento de incidentes
  • Clientes de investigação Sift
  • Clientes de alertas
  • Clientes Asserts

Exemplos de uso direto via CLI:

Para testes com certificados autoassinados:

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

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

Apenas com certificado CA personalizado:

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

Uso programático:

Se você estiver usando esta biblioteca de forma programática, também pode 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 configurar seu próprio servidor HTTP:

Quando consumidores da biblioteca integram as funções de contexto do mcp-grafana em seu próprio http.Server, instale ValidateGrafanaURLMiddleware para rejeitar cabeçalhos X-Grafana-URL malformados com 400 Bad Request (comportamento equivalente ao binário):

mux.Handle(path, mcpgrafana.ValidateGrafanaURLMiddleware(yourMCPHandler))

Ao chamar NewGrafanaClient diretamente (stdio ou construção programática), pré-valide URLs não confiáveis 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)

Ambos os padrões compartilham ValidateGrafanaURL como o validador único.

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

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

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

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

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

Exemplo com servidor HTTP streamable HTTPS:

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

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

Exemplo Docker com TLS do servidor:

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

Endpoint de Health Check

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

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

Nota: O endpoint de health check está disponível apenas ao usar os transportes SSE ou HTTP streamable. Ele 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 Prometheus, tracing distribuído OpenTelemetry e exportação de logs OpenTelemetry, seguindo as convenções semânticas OTel MCP. Tracing e 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 traces e logs. OTEL_EXPORTER_OTLP_PROTOCOL (e suas variantes _TRACES_PROTOCOL / _LOGS_PROTOCOL) não são considerados — gRPC é usado independentemente.

Métricas

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

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

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

Métricas Disponíveis:

MétricaTipoDescrição
mcp_server_operation_duration_secondsHistogramaDuração das operações MCP (labels: 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 (labels: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramaDuração das requisições do servidor HTTP (do otelhttp)

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

Log de requisições lentas

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

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

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

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

O evento de log carrega estes atributos estruturados:

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

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

Tracing

O tracing distribuído é configurado via variáveis de ambiente padrão OTEL_* e funciona independentemente da flag --metrics. Quando OTEL_EXPORTER_OTLP_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 chamada de ferramenta seguem a nomenclatura semconv (tools/call <tool_name>) e incluem atributos como gen_ai.tool.name, mcp.method.name e mcp.session.id. O servidor também suporta propagação de contexto de trace W3C a partir do campo _meta das requisições de chamada de ferramenta.

Logs

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

O log via stderr permanece inalterado quando o log OTLP está habilitado; você pode continuar a confiar nos logs do 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, 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), espelhando o exemplo de tracing acima. Um coletor OTel local é opcional — útil para fan-out, agrupamento 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 consideradas e sobrescrevem suas contrapartes genéricas OTEL_EXPORTER_OTLP_* — veja a especificação do exportador OTel para a lista completa e regras de precedência.

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

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

Exemplo 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

Solução de Problemas

Compatibilidade de Versão 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 normalmente 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 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 este problema.

Desenvolvimento

Contribuições são bem-vindas! Por favor, abra uma issue ou envie um pull request se tiver alguma sugestão ou melhoria.

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

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

make run

Para executar o servidor localmente no modo SSE, use:

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

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

make build-image

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

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

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

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

Testes

Existem três tipos de testes disponíveis:

  1. Testes Unitários (sem dependências externas necessárias):
make test-unit

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

make test
  1. Testes de Integração (requer que os contêineres Docker estejam em execução):
make test-integration
  1. Testes em Nuvem (requer instância e credenciais do Grafana Cloud):
make test-cloud

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

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, por favor, adicione testes de integração para elas. Os testes existentes devem ser um bom ponto de partida.

Linting

Para executar o lint no código, execute:

make lint

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

make lint-jsonschema

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

Licença

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