[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-grafana--mcp-grafana":3,"tool-grafana--mcp-grafana":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",140436,2,"2026-04-05T23:32:43",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":80,"owner_location":80,"owner_email":81,"owner_twitter":76,"owner_website":82,"owner_url":83,"languages":84,"stars":109,"forks":110,"last_commit_at":111,"license":112,"difficulty_score":23,"env_os":113,"env_gpu":114,"env_ram":114,"env_deps":115,"category_tags":120,"github_topics":80,"view_count":23,"oss_zip_url":80,"oss_zip_packed_at":80,"status":16,"created_at":121,"updated_at":122,"faqs":123,"releases":154},2498,"grafana\u002Fmcp-grafana","mcp-grafana","MCP server for Grafana","mcp-grafana 是一个基于模型上下文协议（MCP）构建的服务端工具，旨在为 Grafana 及其生态系统提供标准化的访问接口。它充当了 AI 助手与 Grafana 监控平台之间的桥梁，让大语言模型能够直接读取、分析甚至操作你的监控数据。\n\n在日常运维和开发中，开发者往往需要频繁查询仪表盘状态或调试数据源配置，手动操作繁琐且容易出错。mcp-grafana 解决了这一痛点，允许 AI 客户端（如 Claude Desktop 或 Cursor）通过自然语言指令完成复杂任务。例如，你可以直接询问 AI “帮我查找包含 CPU 使用率的仪表盘”或“提取某个面板的查询语句”，而无需亲自登录后台层层点击。\n\n这款工具特别适合 DevOps 工程师、后端开发者以及数据分析师使用。对于需要快速定位系统瓶颈或自动化生成监控报告的技术人员来说，它能显著降低操作门槛，提升工作效率。普通用户若拥有 Grafana 实例的管理权限，也能借此更直观地理解监控数据。\n\n在技术实现上，mcp-grafana 的一大亮点是其对“上下文窗口”的精细管理。考虑到大型仪表盘的 JSON 数据极其庞大，容易超出 A","mcp-grafana 是一个基于模型上下文协议（MCP）构建的服务端工具，旨在为 Grafana 及其生态系统提供标准化的访问接口。它充当了 AI 助手与 Grafana 监控平台之间的桥梁，让大语言模型能够直接读取、分析甚至操作你的监控数据。\n\n在日常运维和开发中，开发者往往需要频繁查询仪表盘状态或调试数据源配置，手动操作繁琐且容易出错。mcp-grafana 解决了这一痛点，允许 AI 客户端（如 Claude Desktop 或 Cursor）通过自然语言指令完成复杂任务。例如，你可以直接询问 AI “帮我查找包含 CPU 使用率的仪表盘”或“提取某个面板的查询语句”，而无需亲自登录后台层层点击。\n\n这款工具特别适合 DevOps 工程师、后端开发者以及数据分析师使用。对于需要快速定位系统瓶颈或自动化生成监控报告的技术人员来说，它能显著降低操作门槛，提升工作效率。普通用户若拥有 Grafana 实例的管理权限，也能借此更直观地理解监控数据。\n\n在技术实现上，mcp-grafana 的一大亮点是其对“上下文窗口”的精细管理。考虑到大型仪表盘的 JSON 数据极其庞大，容易超出 AI 的处理限制，它提供了多种灵活的数据获取策略：既支持获取精简的仪表盘摘要，也支持通过 JSONPath 表达式仅提取特定字段，还支持针对局部内容的补丁式更新。这种设计不仅节省了 Token 消耗，还大幅提高了 AI 响应的准确性和速度。此外，它还支持执行面板查询并自定义时间范围，为动态数据分析提供了强大支持。只需简单配置 URL 和服务账户令牌，即可快速集成到现有的 MCP 客户端中。","# Grafana MCP server\n\n[![Unit Tests](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Funit.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Funit.yml)\n[![Integration Tests](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fintegration.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fintegration.yml)\n[![E2E Tests](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fe2e.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fe2e.yml)\n[![Go Reference](https:\u002F\u002Fpkg.go.dev\u002Fbadge\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana.svg)](https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana)\n[![MCP Catalog](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgrafana_mcp-grafana_readme_5dfccc754b71.png)](https:\u002F\u002Farchestra.ai\u002Fmcp-catalog\u002Fgrafana__mcp-grafana)\n\nA [Model Context Protocol][mcp] (MCP) server for Grafana.\n\nThis provides access to your Grafana instance and the surrounding ecosystem.\n\n## Quick Start\n\nRequires [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F). Add the following to your MCP client configuration (e.g. Claude Desktop, Cursor):\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-grafana\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\nFor Grafana Cloud, replace `GRAFANA_URL` with your instance URL (e.g. `https:\u002F\u002Fmyinstance.grafana.net`). See [Usage](#usage) for more installation options including Docker, binary, and Helm.\n\n## Requirements\n\n- **Grafana version 9.0 or later** is required for full functionality. Some features, particularly datasource-related operations, may not work correctly with earlier versions due to missing API endpoints.\n\n## Features\n\n_The following features are currently available in MCP server. This list is for informational purposes only and does not represent a roadmap or commitment to future features._\n\n### Dashboards\n\n- **Search for dashboards:** Find dashboards by title or other metadata\n- **Get dashboard by UID:** Retrieve full dashboard details using its unique identifier. _Warning: Large dashboards can consume significant context window space._\n- **Get dashboard summary:** Get a compact overview of a dashboard including title, panel count, panel types, variables, and metadata without the full JSON to minimize context window usage\n- **Get dashboard property:** Extract specific parts of a dashboard using JSONPath expressions (e.g., `$.title`, `$.panels[*].title`) to fetch only needed data and reduce context window consumption\n- **Update or create a dashboard:** Modify existing dashboards or create new ones. _Warning: Requires full dashboard JSON which can consume large amounts of context window space._\n- **Patch dashboard:** Apply specific changes to a dashboard without requiring the full JSON, significantly reducing context window usage for targeted modifications\n- **Get panel queries and datasource info:** Get the title, query string, and datasource information (including UID and type, if available) from every panel in a dashboard\n\n### Run Panel Query\n\n> **Note:** Run panel query tools are **disabled by default**. To enable them, add `runpanelquery` to your `--enabled-tools` flag.\n\n- **Run panel query:** Execute a dashboard panel's query with custom time ranges and variable overrides.\n\n#### Context Window Management\n\nThe dashboard tools now include several strategies to manage context window usage effectively ([issue #101](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F101)):\n\n- **Use `get_dashboard_summary`** for dashboard overview and planning modifications\n- **Use `get_dashboard_property`** with JSONPath when you only need specific dashboard parts\n- **Avoid `get_dashboard_by_uid`** unless you specifically need the complete dashboard JSON\n\n### Datasources\n\n- **List and fetch datasource information:** View all configured datasources and retrieve detailed information about each.\n - _Supported datasource types: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch._\n\n### Query Examples\n\n> **Note:** Query examples tools are **disabled by default**. To enable them, add `examples` to your `--enabled-tools` flag.\n\n- **Get query examples:** Retrieve example queries for different datasource types to learn query syntax.\n\n### Prometheus Querying\n\n- **Query Prometheus:** Execute PromQL queries (supports both instant and range metric queries) against Prometheus datasources.\n- **Query Prometheus metadata:** Retrieve metric metadata, metric names, label names, and label values from Prometheus datasources.\n- **Query histogram percentiles:** Calculate histogram percentile values (p50, p90, p95, p99) using histogram_quantile.\n\n### Loki Querying\n\n- **Query Loki logs and metrics:** Run both log queries and metric queries using LogQL against Loki datasources.\n- **Query Loki metadata:** Retrieve label names, label values, and stream statistics from Loki datasources.\n- **Query Loki patterns:** Retrieve log patterns detected by Loki to identify common log structures and anomalies.\n\n### ClickHouse Querying\n\n> **Note:** ClickHouse tools are **disabled by default**. To enable them, add `clickhouse` to your `--enabled-tools` flag.\n\n- **List ClickHouse tables:** List all tables in a ClickHouse database with row counts and sizes.\n- **Describe table schema:** Get column names, types, and metadata for a ClickHouse table.\n- **Query ClickHouse:** Execute SQL queries with Grafana macro and variable substitution support.\n\n### CloudWatch Querying\n\n> **Note:** CloudWatch tools are **disabled by default**. To enable them, add `cloudwatch` to your `--enabled-tools` flag.\n\n- **List CloudWatch namespaces:** Discover available AWS CloudWatch namespaces.\n- **List CloudWatch metrics:** List metrics available in a specific namespace.\n- **List CloudWatch dimensions:** Get dimensions for filtering metric queries.\n- **Query CloudWatch:** Execute CloudWatch metric queries with time range support.\n\n### Log Search\n\n> **Note:** Search logs tools are **disabled by default**. To enable them, add `searchlogs` to your `--enabled-tools` flag.\n\n- **Search logs:** High-level log search across ClickHouse (OTel format) and Loki datasources.\n\n### Elasticsearch Querying\n\n> **Note:** Elasticsearch tools are **disabled by default**. To enable them, add `elasticsearch` to your `--enabled-tools` flag.\n\n- **Query Elasticsearch:** Execute search queries against Elasticsearch datasources using either Lucene query syntax or Elasticsearch Query DSL. Supports filtering by time range and retrieving logs, metrics, or any indexed data. Returns documents with their index, ID, source fields, and optional relevance score.\n\n### Incidents\n\n- **Search, create, and update incidents:** Manage incidents in Grafana Incident, including searching, creating, and adding activities to incidents.\n\n### Sift Investigations\n\n- **List Sift investigations:** Retrieve a list of Sift investigations, with support for a limit parameter.\n- **Get Sift investigation:** Retrieve details of a specific Sift investigation by its UUID.\n- **Get Sift analyses:** Retrieve a specific analysis from a Sift investigation.\n- **Find error patterns in logs:** Detect elevated error patterns in Loki logs using Sift.\n- **Find slow requests:** Detect slow requests using Sift (Tempo).\n\n### Alerting\n\n- **List and fetch alert rule information:** View alert rules and their statuses (firing\u002Fnormal\u002Ferror\u002Fetc.) in Grafana. Supports both Grafana-managed rules and datasource-managed rules from Prometheus or Loki datasources.\n- **Create and update alert rules:** Create new alert rules or modify existing ones.\n- **Delete alert rules:** Remove alert rules by UID.\n- **Manage alerting routing:** View notification policies, contact points, and time intervals. Supports both Grafana-managed contact points and receivers from external Alertmanager datasources (Prometheus Alertmanager, Mimir, Cortex).\n\n### Grafana OnCall\n\n- **List and manage schedules:** View and manage on-call schedules in Grafana OnCall.\n- **Get shift details:** Retrieve detailed information about specific on-call shifts.\n- **Get current on-call users:** See which users are currently on call for a schedule.\n- **List teams and users:** View all OnCall teams and users.\n- **List alert groups:** View and filter alert groups from Grafana OnCall by various criteria including state, integration, labels, and time range.\n- **Get alert group details:** Retrieve detailed information about a specific alert group by its ID.\n\n### Admin\n\n> **Note:** Admin tools are **disabled by default**. To enable them, include `admin` in your `--enabled-tools` flag.\n- **List teams:** View all configured teams in Grafana.\n- **List Users:** View all users in an organization in Grafana.\n- **List all roles:** List all Grafana roles, with an optional filter for delegatable roles.\n- **Get role details:** Get details for a specific Grafana role by UID.\n- **List assignments for a role:** List all users, teams, and service accounts assigned to a role.\n- **List roles for users:** List all roles assigned to one or more users.\n- **List roles for teams:** List all roles assigned to one or more teams.\n- **List permissions for a resource:** List all permissions defined for a specific resource (dashboard, datasource, folder, etc.).\n- **Describe a Grafana resource:** List available permissions and assignment capabilities for a resource type.\n\n### Navigation\n\n- **Generate deeplinks:** Create accurate deeplink URLs for Grafana resources instead of relying on LLM URL guessing.\n - **Dashboard links:** Generate direct links to dashboards using their UID (e.g., `http:\u002F\u002Flocalhost:3000\u002Fd\u002Fdashboard-uid`)\n - **Panel links:** Create links to specific panels within dashboards with viewPanel parameter (e.g., `http:\u002F\u002Flocalhost:3000\u002Fd\u002Fdashboard-uid?viewPanel=5`)\n - **Explore links:** Generate links to Grafana Explore with pre-configured datasources (e.g., `http:\u002F\u002Flocalhost:3000\u002Fexplore?left={\"datasource\":\"prometheus-uid\"}`)\n - **Time range support:** Add time range parameters to links (`from=now-1h&to=now`)\n - **Custom parameters:** Include additional query parameters like dashboard variables or refresh intervals\n\n### Annotations\n\n- **Get Annotations:** Query annotations with filters. Supports time range, dashboard UID, tags, and match mode.\n- **Create Annotation:** Create a new annotation on a dashboard or panel.\n- **Create Graphite Annotation:** Create annotations using Graphite format (`what`, `when`, `tags`, `data`).\n- **Update Annotation:** Replace all fields of an existing annotation (full update).\n- **Patch Annotation:** Update only specific fields of an annotation (partial update).\n- **Get Annotation Tags:** List available annotation tags with optional filtering.\n\n### Rendering\n\n- **Get panel or dashboard image:** Render a Grafana dashboard panel or full dashboard as a PNG image. Returns the image as base64 encoded data for use in reports, alerts, or presentations. Supports customizing dimensions, time range, theme, scale, and dashboard variables.\n - _Note: Requires the [Grafana Image Renderer](https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Fsetup-grafana\u002Fimage-rendering\u002F) service to be installed and configured._\n\nThe list of tools is configurable, so you can choose which tools you want to make available to the MCP client.\nThis is useful if you don't use certain functionality or if you don't want to take up too much of the context window.\nTo disable a category of tools, use the `--disable-\u003Ccategory>` flag when starting the server. For example, to disable\nthe OnCall tools, use `--disable-oncall`, or to disable navigation deeplink generation, use `--disable-navigation`.\n\n\n#### RBAC Permissions\n\nEach tool requires specific RBAC permissions to function properly. When creating a service account for the MCP server, ensure it has the necessary permissions based on which tools you plan to use. The permissions listed are the minimum required actions - you may also need appropriate scopes (e.g., `datasources:*`, `dashboards:*`, `folders:*`) depending on your use case.\n\nTip: If you're not familiar with Grafana RBAC or you want a quicker, simpler setup instead of configuring many granular scopes, you can assign a built-in role such as `Editor` to the service account. The `Editor` role grants broad read\u002Fwrite access that will allow most MCP server operations; it is less granular (and therefore less restrictive) than manually-applied scopes, so use it only when convenience is more important than strict least-privilege access.\n\n**Note:** Grafana Incident and Sift tools use basic Grafana roles instead of fine-grained RBAC permissions:\n- **Viewer role:** Required for read-only operations (list incidents, get investigations)\n- **Editor role:** Required for write operations (create incidents, modify investigations)\n\nFor more information about Grafana RBAC, see the [official documentation](https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Fadministration\u002Froles-and-permissions\u002Faccess-control\u002F).\n\n#### RBAC Scopes\n\nScopes define the specific resources that permissions apply to. Each action requires both the appropriate permission and scope combination.\n\n**Common Scope Patterns:**\n\n- **Broad access:** Use `*` wildcards for organization-wide access\n\n - `datasources:*` - Access to all datasources\n - `dashboards:*` - Access to all dashboards\n - `folders:*` - Access to all folders\n - `teams:*` - Access to all teams\n\n- **Limited access:** Use specific UIDs or IDs to restrict access to individual resources\n - `datasources:uid:prometheus-uid` - Access only to a specific Prometheus datasource\n - `dashboards:uid:abc123` - Access only to dashboard with UID `abc123`\n - `folders:uid:xyz789` - Access only to folder with UID `xyz789`\n - `teams:id:5` - Access only to team with ID `5`\n - `global.users:id:123` - Access only to user with ID `123`\n\n**Examples:**\n\n- **Full MCP server access:** Grant broad permissions for all tools\n\n ```\n datasources:* (datasources:read, datasources:query)\n dashboards:* (dashboards:read, dashboards:create, dashboards:write)\n folders:* (for dashboard creation and alert rules)\n teams:* (teams:read)\n global.users:* (users:read)\n ```\n\n- **Limited datasource access:** Only query specific Prometheus and Loki instances\n\n ```\n datasources:uid:prometheus-prod (datasources:query)\n datasources:uid:loki-prod (datasources:query)\n ```\n\n- **Dashboard-specific access:** Read only specific dashboards\n ```\n dashboards:uid:monitoring-dashboard (dashboards:read)\n dashboards:uid:alerts-dashboard (dashboards:read)\n ```\n\n### Tools\n\n| Tool | Category | Description | Required RBAC Permissions | Required Scopes |\n| --------------------------------- | ----------- | ------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------- |\n| `list_teams` | Admin | List all teams | `teams:read` | `teams:*` or `teams:id:1` |\n| `list_users_by_org` | Admin | List all users in an organization | `users:read` | `global.users:*` or `global.users:id:123` |\n| `list_all_roles` | Admin | List all Grafana roles | `roles:read` | `roles:*` |\n| `get_role_details` | Admin | Get details for a Grafana role | `roles:read` | `roles:uid:editor` |\n| `get_role_assignments` | Admin | List assignments for a role | `roles:read` | `roles:uid:editor` |\n| `list_user_roles` | Admin | List roles for users | `roles:read` | `global.users:id:123` |\n| `list_team_roles` | Admin | List roles for teams | `roles:read` | `teams:id:7` |\n| `get_resource_permissions`| Admin | List permissions for a resource | `permissions:read` | `dashboards:uid:abcd1234` |\n| `get_resource_description`| Admin | Describe a Grafana resource type | `permissions:read` | `dashboards:*` |\n| `search_dashboards` | Search | Search for dashboards | `dashboards:read` | `dashboards:*` or `dashboards:uid:abc123` |\n| `get_dashboard_by_uid` | Dashboard | Get a dashboard by uid | `dashboards:read` | `dashboards:uid:abc123` |\n| `update_dashboard` | Dashboard | Update or create a new dashboard | `dashboards:create`, `dashboards:write` | `dashboards:*`, `folders:*` or `folders:uid:xyz789` |\n| `get_dashboard_panel_queries` | Dashboard | Get panel title, queries, datasource UID and type from a dashboard | `dashboards:read` | `dashboards:uid:abc123` |\n| `run_panel_query` | RunPanelQuery* | Execute one or more dashboard panel queries | `dashboards:read`, `datasources:query` | `dashboards:uid:*`, `datasources:uid:*` |\n| `get_dashboard_property` | Dashboard | Extract specific parts of a dashboard using JSONPath expressions | `dashboards:read` | `dashboards:uid:abc123` |\n| `get_dashboard_summary` | Dashboard | Get a compact summary of a dashboard without full JSON | `dashboards:read` | `dashboards:uid:abc123` |\n| `list_datasources` | Datasources | List datasources | `datasources:read` | `datasources:*` |\n| `get_datasource` | Datasources | Get a datasource by UID or name | `datasources:read` | `datasources:uid:prometheus-uid` |\n| `get_query_examples` | Examples* | Get example queries for a datasource type | `datasources:read` | `datasources:*` |\n| `query_prometheus` | Prometheus | Execute a query against a Prometheus datasource | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_metric_metadata` | Prometheus | List metric metadata | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_metric_names` | Prometheus | List available metric names | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_label_names` | Prometheus | List label names matching a selector | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_label_values` | Prometheus | List values for a specific label | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `query_prometheus_histogram` | Prometheus | Calculate histogram percentile values | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_incidents` | Incident | List incidents in Grafana Incident | Viewer role | N\u002FA |\n| `create_incident` | Incident | Create an incident in Grafana Incident | Editor role | N\u002FA |\n| `add_activity_to_incident` | Incident | Add an activity item to an incident in Grafana Incident | Editor role | N\u002FA |\n| `get_incident` | Incident | Get a single incident by ID | Viewer role | N\u002FA |\n| `query_loki_logs` | Loki | Query and retrieve logs using LogQL (either log or metric queries) | `datasources:query` | `datasources:uid:loki-uid` |\n| `list_loki_label_names` | Loki | List all available label names in logs | `datasources:query` | `datasources:uid:loki-uid` |\n| `list_loki_label_values` | Loki | List values for a specific log label | `datasources:query` | `datasources:uid:loki-uid` |\n| `query_loki_stats` | Loki | Get statistics about log streams | `datasources:query` | `datasources:uid:loki-uid` |\n| `query_loki_patterns` | Loki | Query detected log patterns to identify common structures | `datasources:query` | `datasources:uid:loki-uid` |\n| `list_clickhouse_tables` | ClickHouse* | List tables in a ClickHouse database | `datasources:query` | `datasources:uid:*` |\n| `describe_clickhouse_table` | ClickHouse* | Get table schema with column types | `datasources:query` | `datasources:uid:*` |\n| `query_clickhouse` | ClickHouse* | Execute SQL queries with macro substitution | `datasources:query` | `datasources:uid:*` |\n| `list_cloudwatch_namespaces` | CloudWatch* | List available AWS CloudWatch namespaces | `datasources:query` | `datasources:uid:*` |\n| `list_cloudwatch_metrics` | CloudWatch* | List metrics in a namespace | `datasources:query` | `datasources:uid:*` |\n| `list_cloudwatch_dimensions` | CloudWatch* | List dimensions for a metric | `datasources:query` | `datasources:uid:*` |\n| `query_cloudwatch` | CloudWatch* | Execute CloudWatch metric queries | `datasources:query` | `datasources:uid:*` |\n| `search_logs` | SearchLogs* | Search logs across ClickHouse and Loki | `datasources:query` | `datasources:uid:*` |\n| `query_elasticsearch` | Elasticsearch* | Query Elasticsearch using Lucene syntax or Query DSL | `datasources:query` | `datasources:uid:elasticsearch-uid` |\n| `alerting_manage_rules` | Alerting | Manage alert rules (list, get, versions, create, update, delete) | `alert.rules:read` + `alert.rules:write` for mutations | `folders:*` or `folders:uid:alerts-folder` |\n| `alerting_manage_routing` | Alerting | Manage notification policies, contact points, and time intervals | `alert.notifications:read` | Global scope |\n| `list_oncall_schedules` | OnCall | List schedules from Grafana OnCall | `grafana-oncall-app.schedules:read` | Plugin-specific scopes |\n| `get_oncall_shift` | OnCall | Get details for a specific OnCall shift | `grafana-oncall-app.schedules:read` | Plugin-specific scopes |\n| `get_current_oncall_users` | OnCall | Get users currently on-call for a specific schedule | `grafana-oncall-app.schedules:read` | Plugin-specific scopes |\n| `list_oncall_teams` | OnCall | List teams from Grafana OnCall | `grafana-oncall-app.user-settings:read` | Plugin-specific scopes |\n| `list_oncall_users` | OnCall | List users from Grafana OnCall | `grafana-oncall-app.user-settings:read` | Plugin-specific scopes |\n| `list_alert_groups` | OnCall | List alert groups from Grafana OnCall with filtering options | `grafana-oncall-app.alert-groups:read` | Plugin-specific scopes |\n| `get_alert_group` | OnCall | Get a specific alert group from Grafana OnCall by its ID | `grafana-oncall-app.alert-groups:read` | Plugin-specific scopes |\n| `get_sift_investigation` | Sift | Retrieve an existing Sift investigation by its UUID | Viewer role | N\u002FA |\n| `get_sift_analysis` | Sift | Retrieve a specific analysis from a Sift investigation | Viewer role | N\u002FA |\n| `list_sift_investigations` | Sift | Retrieve a list of Sift investigations with an optional limit | Viewer role | N\u002FA |\n| `find_error_pattern_logs` | Sift | Finds elevated error patterns in Loki logs. | Editor role | N\u002FA |\n| `find_slow_requests` | Sift | Finds slow requests from the relevant tempo datasources. | Editor role | N\u002FA |\n| `list_pyroscope_label_names` | Pyroscope | List label names matching a selector | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `list_pyroscope_label_values` | Pyroscope | List label values matching a selector for a label name | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `list_pyroscope_profile_types` | Pyroscope | List available profile types | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `fetch_pyroscope_profile` | Pyroscope | Fetches a profile in DOT format for analysis | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `get_assertions` | Asserts | Get assertion summary for a given entity | Plugin-specific permissions | Plugin-specific scopes |\n| `generate_deeplink` | Navigation | Generate accurate deeplink URLs for Grafana resources | None (read-only URL generation) | N\u002FA |\n| `get_annotations` | Annotations | Fetch annotations with filters | `annotations:read` | `annotations:*` or `annotations:id:123` |\n| `create_annotation` | Annotations | Create a new annotation (standard or Graphite format) | `annotations:write` | `annotations:*` |\n| `update_annotation` | Annotations | Update specific fields of an annotation (partial update) | `annotations:write` | `annotations:*` |\n| `get_annotation_tags` | Annotations | List annotation tags with optional filtering | `annotations:read` | `annotations:*` |\n| `get_panel_image` | Rendering | Render a dashboard panel or full dashboard as a PNG image | `dashboards:read` | `dashboards:uid:abc123` |\n\n_* Disabled by default. Add category to `--enabled-tools` to enable._\n\n## CLI Flags Reference\n\nThe `mcp-grafana` binary supports various command-line flags for configuration:\n\n**Transport Options:**\n- `-t, --transport`: Transport type (`stdio`, `sse`, or `streamable-http`) - default: `stdio`\n- `--address`: The host and port for SSE\u002Fstreamable-http server - default: `localhost:8000`\n- `--base-path`: Base path for the SSE\u002Fstreamable-http server\n- `--endpoint-path`: Endpoint path for the streamable-http server - default: `\u002F`\n\n**Debug and Logging:**\n- `--debug`: Enable debug mode for detailed HTTP request\u002Fresponse logging\n- `--log-level`: Log level (`debug`, `info`, `warn`, `error`) - default: `info`\n\n**Observability:**\n- `--metrics`: Enable Prometheus metrics endpoint at `\u002Fmetrics`\n- `--metrics-address`: Separate address for metrics server (e.g., `:9090`). If empty, metrics are served on the main server\n\n**Session Management:**\n- `--session-idle-timeout-minutes`: Session idle timeout in minutes. Sessions with no activity for this duration are automatically reaped - default: `30`. Set to `0` to disable session reaping. Only relevant for SSE and streamable-http transports.\n\n**Tool Configuration:**\n- `--enabled-tools`: Comma-separated list of enabled categories - default: all categories except `admin`, to enable admin tools, add `admin` to the list (e.g., `\"search,datasource,...,admin\"`)\n- `--max-loki-log-limit`: Maximum number of log lines returned per `query_loki_logs` call - default: `100`. Note: Set this at least 1 below Loki's server-side `max_entries_limit_per_query` to allow truncation detection (the tool requests `limit+1` internally to detect if more data exists).\n- `--disable-search`: Disable search tools\n- `--disable-datasource`: Disable datasource tools\n- `--disable-incident`: Disable incident tools\n- `--disable-prometheus`: Disable prometheus tools\n- `--disable-write`: Disable write tools (create\u002Fupdate operations)\n- `--disable-loki`: Disable loki tools\n- `--disable-elasticsearch`: Disable elasticsearch tools\n- `--disable-alerting`: Disable alerting tools\n- `--disable-dashboard`: Disable dashboard tools\n- `--disable-oncall`: Disable oncall tools\n- `--disable-asserts`: Disable asserts tools\n- `--disable-sift`: Disable sift tools\n- `--disable-admin`: Disable admin tools\n- `--disable-pyroscope`: Disable pyroscope tools\n- `--disable-navigation`: Disable navigation tools\n- `--disable-rendering`: Disable rendering tools (panel\u002Fdashboard image export)\n- `--disable-cloudwatch`: Disable CloudWatch tools\n- `--disable-examples`: Disable query examples tools\n- `--disable-clickhouse`: Disable ClickHouse tools\n- `--disable-searchlogs`: Disable search_logs tool\n- `--disable-runpanelquery`: Disable run panel query tools\n\n### Read-Only Mode\n\nThe `--disable-write` flag provides a way to run the MCP server in read-only mode, preventing any write operations to your Grafana instance. This is useful for scenarios where you want to provide safe, read-only access such as:\n\n- Using service accounts with limited read-only permissions\n- Providing AI assistants with observability data without modification capabilities\n- Running in production environments where write access should be restricted\n- Testing and development scenarios where you want to prevent accidental modifications\n\nWhen `--disable-write` is enabled, the following write operations are disabled:\n\n**Dashboard Tools:**\n- `update_dashboard`\n\n**Folder Tools:**\n- `create_folder`\n\n**Incident Tools:**\n- `create_incident`\n- `add_activity_to_incident`\n\n**Alerting Tools:**\n- `alerting_manage_rules` (create, update, delete operations)\n\n**Annotation Tools:**\n- `create_annotation`\n- `update_annotation`\n\n**Sift Tools:**\n- `find_error_pattern_logs` (creates investigations)\n- `find_slow_requests` (creates investigations)\n\nAll read operations remain available, allowing you to query dashboards, run PromQL\u002FLogQL queries, list resources, and retrieve data.\n\n**Client TLS Configuration (for Grafana connections):**\n- `--tls-cert-file`: Path to TLS certificate file for client authentication\n- `--tls-key-file`: Path to TLS private key file for client authentication\n- `--tls-ca-file`: Path to TLS CA certificate file for server verification\n- `--tls-skip-verify`: Skip TLS certificate verification (insecure)\n\n**Server TLS Configuration (streamable-http transport only):**\n- `--server.tls-cert-file`: Path to TLS certificate file for server HTTPS\n- `--server.tls-key-file`: Path to TLS private key file for server HTTPS\n\n## Usage\n\nThis MCP server works with both local Grafana instances and Grafana Cloud. For Grafana Cloud, use your instance URL (e.g., `https:\u002F\u002Fmyinstance.grafana.net`) instead of `http:\u002F\u002Flocalhost:3000` in the configuration examples below.\n\n1. If using service account token authentication, create a service account in Grafana with enough permissions to use the tools you want to use,\n generate a service account token, and copy it to the clipboard for use in the configuration file.\n Follow the [Grafana service account documentation][service-account] for details on creating service account tokens.\n Tip: If you're not comfortable configuring fine-grained RBAC scopes, a simpler (but less restrictive) option is to assign the built-in `Editor` role to the service account. This grants broad read\u002Fwrite access that covers most MCP server operations — use it when convenience outweighs strict least-privilege requirements.\n\n > **Note:** The environment variable `GRAFANA_API_KEY` is deprecated and will be removed in a future version. Please migrate to using `GRAFANA_SERVICE_ACCOUNT_TOKEN` instead. The old variable name will continue to work for backward compatibility but will show deprecation warnings.\n\n### Multi-Organization Support\n \nYou can specify which organization to interact with using either:\n\n- **Environment variable:** Set `GRAFANA_ORG_ID` to the numeric organization ID\n- **HTTP header:** Set `X-Grafana-Org-Id` when using SSE or streamable HTTP transports (header takes precedence over environment variable - meaning you can set a default org as well).\n\nWhen an organization ID is provided, the MCP server will set the `X-Grafana-Org-Id` header on all requests to Grafana, ensuring that operations are performed within the specified organization context.\n\n**Example with organization ID:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_USERNAME\": \"\u003Cyour username>\",\n \"GRAFANA_PASSWORD\": \"\u003Cyour password>\",\n \"GRAFANA_ORG_ID\": \"2\"\n }\n }\n }\n}\n```\n\n### Custom HTTP Headers\n\nYou can add arbitrary HTTP headers to all Grafana API requests using the `GRAFANA_EXTRA_HEADERS` environment variable. The value should be a JSON object mapping header names to values.\n\n**Example with custom headers:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour token>\",\n \"GRAFANA_EXTRA_HEADERS\": \"{\\\"X-Custom-Header\\\": \\\"custom-value\\\", \\\"X-Tenant-ID\\\": \\\"tenant-123\\\"}\"\n }\n }\n }\n}\n```\n\n2. You have several options to install `mcp-grafana`:\n\n - **uvx (recommended)**: If you have [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F) installed, no extra setup is needed — `uvx` will automatically download and run the server:\n\n ```bash\n uvx mcp-grafana\n ```\n\n - **Docker image**: Use the pre-built Docker image from Docker Hub.\n\n **Important**: The Docker image's entrypoint is configured to run the MCP server in SSE mode by default, but most users will want to use STDIO mode for direct integration with AI assistants like Claude Desktop:\n\n 1. **STDIO Mode**: For stdio mode you must explicitly override the default with `-t stdio` and include the `-i` flag to keep stdin open:\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n # For local Grafana:\n docker run --rm -i -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana -t stdio\n # For Grafana Cloud:\n docker run --rm -i -e GRAFANA_URL=https:\u002F\u002Fmyinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana -t stdio\n ```\n\n 2. **SSE Mode**: In this mode, the server runs as an HTTP server that clients connect to. You must expose port 8000 using the `-p` flag:\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n docker run --rm -p 8000:8000 -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana\n ```\n\n 3. **Streamable HTTP Mode**: In this mode, the server operates as an independent process that can handle multiple client connections. You must expose port 8000 using the `-p` flag: For this mode you must explicitly override the default with `-t streamable-http`\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n docker run --rm -p 8000:8000 -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana -t streamable-http\n ```\n\n For HTTPS streamable HTTP mode with server TLS certificates:\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n docker run --rm -p 8443:8443 \\\n -v \u002Fpath\u002Fto\u002Fcerts:\u002Fcerts:ro \\\n -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 \\\n -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> \\\n grafana\u002Fmcp-grafana \\\n -t streamable-http \\\n -addr :8443 \\\n --server.tls-cert-file \u002Fcerts\u002Fserver.crt \\\n --server.tls-key-file \u002Fcerts\u002Fserver.key\n ```\n\n - **Download binary**: Download the latest release of `mcp-grafana` from the [releases page](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Freleases) and place it in your `$PATH`.\n\n - **Build from source**: If you have a Go toolchain installed you can also build and install it from source, using the `GOBIN` environment variable\n to specify the directory where the binary should be installed. This should also be in your `PATH`.\n\n ```bash\n GOBIN=\"$HOME\u002Fgo\u002Fbin\" go install github.com\u002Fgrafana\u002Fmcp-grafana\u002Fcmd\u002Fmcp-grafana@latest\n ```\n\n - **Deploy to Kubernetes using Helm**: use the [Helm chart from the Grafana helm-charts repository](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fhelm-charts\u002Ftree\u002Fmain\u002Fcharts\u002Fgrafana-mcp)\n\n ```bash\n helm repo add grafana https:\u002F\u002Fgrafana.github.io\u002Fhelm-charts\n helm install --set grafana.apiKey=\u003CGrafana_ApiKey> --set grafana.url=\u003CGrafanaUrl> my-release grafana\u002Fgrafana-mcp\n ```\n\n\n3. Add the server configuration to your client configuration file. For example, for Claude Desktop:\n\n **If using uvx:**\n\n ```json\n {\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-grafana\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n }\n ```\n\n **If using the binary:**\n\n ```json\n {\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F Or \"https:\u002F\u002Fmyinstance.grafana.net\" for Grafana Cloud\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\",\n \u002F\u002F If using username\u002Fpassword authentication\n \"GRAFANA_USERNAME\": \"\u003Cyour username>\",\n \"GRAFANA_PASSWORD\": \"\u003Cyour password>\",\n \u002F\u002F Optional: specify organization ID for multi-org support\n \"GRAFANA_ORG_ID\": \"1\"\n }\n }\n }\n }\n ```\n\n> Note: if you see `Error: spawn mcp-grafana ENOENT` in Claude Desktop, you need to specify the full path to `mcp-grafana`.\n\n**If using Docker:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"GRAFANA_URL\",\n \"-e\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\",\n \"grafana\u002Fmcp-grafana\",\n \"-t\",\n \"stdio\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F Or \"https:\u002F\u002Fmyinstance.grafana.net\" for Grafana Cloud\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\",\n \u002F\u002F If using username\u002Fpassword authentication\n \"GRAFANA_USERNAME\": \"\u003Cyour username>\",\n \"GRAFANA_PASSWORD\": \"\u003Cyour password>\",\n \u002F\u002F Optional: specify organization ID for multi-org support\n \"GRAFANA_ORG_ID\": \"1\"\n }\n }\n }\n}\n```\n\n> Note: The `-t stdio` argument is essential here because it overrides the default SSE mode in the Docker image.\n\n**Using VSCode with remote MCP server**\n\nIf you're using VSCode and running the MCP server in SSE mode (which is the default when using the Docker image without overriding the transport), make sure your `.vscode\u002Fsettings.json` includes the following:\n\n```json\n\"mcp\": {\n \"servers\": {\n \"grafana\": {\n \"type\": \"sse\",\n \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fsse\"\n }\n }\n}\n```\n\nFor HTTPS streamable HTTP mode with server TLS certificates:\n\n```json\n\"mcp\": {\n \"servers\": {\n \"grafana\": {\n \"type\": \"sse\",\n \"url\": \"https:\u002F\u002Flocalhost:8443\u002Fsse\"\n }\n }\n}\n```\n\n### Debug Mode\n\nYou can enable debug mode for the Grafana transport by adding the `-debug` flag to the command. This will provide detailed logging of HTTP requests and responses between the MCP server and the Grafana API, which can be helpful for troubleshooting.\n\nTo use debug mode with the Claude Desktop configuration, update your config as follows:\n\n**If using the binary:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [\"-debug\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F Or \"https:\u002F\u002Fmyinstance.grafana.net\" for Grafana Cloud\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\n**If using Docker:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"GRAFANA_URL\",\n \"-e\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\",\n \"grafana\u002Fmcp-grafana\",\n \"-t\",\n \"stdio\",\n \"-debug\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F Or \"https:\u002F\u002Fmyinstance.grafana.net\" for Grafana Cloud\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\n> Note: As with the standard configuration, the `-t stdio` argument is required to override the default SSE mode in the Docker image.\n\n### TLS Configuration\n\nIf your Grafana instance is behind mTLS or requires custom TLS certificates, you can configure the MCP server to use custom certificates. The server supports the following TLS configuration options:\n\n- `--tls-cert-file`: Path to TLS certificate file for client authentication\n- `--tls-key-file`: Path to TLS private key file for client authentication\n- `--tls-ca-file`: Path to TLS CA certificate file for server verification\n- `--tls-skip-verify`: Skip TLS certificate verification (insecure, use only for testing)\n\n**Example with client certificate authentication:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [\n \"--tls-cert-file\",\n \"\u002Fpath\u002Fto\u002Fclient.crt\",\n \"--tls-key-file\",\n \"\u002Fpath\u002Fto\u002Fclient.key\",\n \"--tls-ca-file\",\n \"\u002Fpath\u002Fto\u002Fca.crt\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"https:\u002F\u002Fsecure-grafana.example.com\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\n**Example with Docker:**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-v\",\n \"\u002Fpath\u002Fto\u002Fcerts:\u002Fcerts:ro\",\n \"-e\",\n \"GRAFANA_URL\",\n \"-e\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\",\n \"grafana\u002Fmcp-grafana\",\n \"-t\",\n \"stdio\",\n \"--tls-cert-file\",\n \"\u002Fcerts\u002Fclient.crt\",\n \"--tls-key-file\",\n \"\u002Fcerts\u002Fclient.key\",\n \"--tls-ca-file\",\n \"\u002Fcerts\u002Fca.crt\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"https:\u002F\u002Fsecure-grafana.example.com\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\nThe TLS configuration is applied to all HTTP clients used by the MCP server, including:\n\n- The main Grafana OpenAPI client\n- Prometheus datasource clients\n- Loki datasource clients\n- Incident management clients\n- Sift investigation clients\n- Alerting clients\n- Asserts clients\n\n**Direct CLI Usage Examples:**\n\nFor testing with self-signed certificates:\n\n```bash\n.\u002Fmcp-grafana --tls-skip-verify -debug\n```\n\nWith client certificate authentication:\n\n```bash\n.\u002Fmcp-grafana \\\n --tls-cert-file \u002Fpath\u002Fto\u002Fclient.crt \\\n --tls-key-file \u002Fpath\u002Fto\u002Fclient.key \\\n --tls-ca-file \u002Fpath\u002Fto\u002Fca.crt \\\n -debug\n```\n\nWith custom CA certificate only:\n\n```bash\n.\u002Fmcp-grafana --tls-ca-file \u002Fpath\u002Fto\u002Fca.crt\n```\n\n**Programmatic Usage:**\n\nIf you're using this library programmatically, you can also create TLS-enabled context functions:\n\n```go\n\u002F\u002F Using struct literals\ntlsConfig := &mcpgrafana.TLSConfig{\n CertFile: \"\u002Fpath\u002Fto\u002Fclient.crt\",\n KeyFile: \"\u002Fpath\u002Fto\u002Fclient.key\",\n CAFile: \"\u002Fpath\u002Fto\u002Fca.crt\",\n}\ngrafanaConfig := mcpgrafana.GrafanaConfig{\n Debug: true,\n TLSConfig: tlsConfig,\n}\ncontextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)\n\n\u002F\u002F Or inline\ngrafanaConfig := mcpgrafana.GrafanaConfig{\n Debug: true,\n TLSConfig: &mcpgrafana.TLSConfig{\n CertFile: \"\u002Fpath\u002Fto\u002Fclient.crt\",\n KeyFile: \"\u002Fpath\u002Fto\u002Fclient.key\",\n CAFile: \"\u002Fpath\u002Fto\u002Fca.crt\",\n },\n}\ncontextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)\n```\n\n### Server TLS Configuration (Streamable HTTP Transport Only)\n\nWhen using the streamable HTTP transport (`-t streamable-http`), you can configure the MCP server to serve HTTPS instead of HTTP. This is useful when you need to secure the connection between your MCP client and the server itself.\n\nThe server supports the following TLS configuration options for the streamable HTTP transport:\n\n- `--server.tls-cert-file`: Path to TLS certificate file for server HTTPS (required for TLS)\n- `--server.tls-key-file`: Path to TLS private key file for server HTTPS (required for TLS)\n\n**Note**: These flags are completely separate from the client TLS flags documented above. The client TLS flags configure how the MCP server connects to Grafana, while these server TLS flags configure how clients connect to the MCP server when using streamable HTTP transport.\n\n**Example with HTTPS streamable HTTP server:**\n\n```bash\n.\u002Fmcp-grafana \\\n -t streamable-http \\\n --server.tls-cert-file \u002Fpath\u002Fto\u002Fserver.crt \\\n --server.tls-key-file \u002Fpath\u002Fto\u002Fserver.key \\\n -addr :8443\n```\n\nThis would start the MCP server on HTTPS port 8443. Clients would then connect to `https:\u002F\u002Flocalhost:8443\u002F` instead of `http:\u002F\u002Flocalhost:8000\u002F`.\n\n**Docker example with server TLS:**\n\n```bash\ndocker run --rm -p 8443:8443 \\\n -v \u002Fpath\u002Fto\u002Fcerts:\u002Fcerts:ro \\\n -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 \\\n -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> \\\n grafana\u002Fmcp-grafana \\\n -t streamable-http \\\n -addr :8443 \\\n --server.tls-cert-file \u002Fcerts\u002Fserver.crt \\\n --server.tls-key-file \u002Fcerts\u002Fserver.key\n```\n\n### Health Check Endpoint\n\nWhen using the SSE (`-t sse`) or streamable HTTP (`-t streamable-http`) transports, the MCP server exposes a health check endpoint at `\u002Fhealthz`. This endpoint can be used by load balancers, monitoring systems, or orchestration platforms to verify that the server is running and accepting connections.\n\n**Endpoint:** `GET \u002Fhealthz`\n\n**Response:**\n- Status Code: `200 OK`\n- Body: `ok`\n\n**Example usage:**\n\n```bash\n# For streamable HTTP or SSE transport on default port\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealthz\n\n# With custom address\ncurl http:\u002F\u002Flocalhost:9090\u002Fhealthz\n```\n\n**Note:** The health check endpoint is only available when using SSE or streamable HTTP transports. It is not available when using the stdio transport (`-t stdio`), as stdio does not expose an HTTP server.\n\n### Observability\n\nThe MCP server supports Prometheus metrics and OpenTelemetry distributed tracing, following the [OTel MCP semantic conventions](https:\u002F\u002Fopentelemetry.io\u002Fdocs\u002Fspecs\u002Fsemconv\u002Fgen-ai\u002Fmcp\u002F).\n\n#### Metrics\n\nWhen using the SSE or streamable HTTP transports, enable Prometheus metrics with the `--metrics` flag:\n\n```bash\n# Metrics served on the main server at \u002Fmetrics\n.\u002Fmcp-grafana -t streamable-http --metrics\n\n# Metrics served on a separate address\n.\u002Fmcp-grafana -t streamable-http --metrics --metrics-address :9090\n```\n\n**Available Metrics:**\n\n| Metric | Type | Description |\n|--------|------|-------------|\n| `mcp_server_operation_duration_seconds` | Histogram | Duration of MCP operations (labels: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`) |\n| `mcp_server_session_duration_seconds` | Histogram | Duration of MCP client sessions (labels: `network_transport`, `mcp_protocol_version`) |\n| `http_server_request_duration_seconds` | Histogram | Duration of HTTP server requests (from otelhttp) |\n\n**Note:** Metrics are only available when using SSE or streamable HTTP transports. They are not available with the stdio transport.\n\n#### Tracing\n\nDistributed tracing is configured via standard `OTEL_*` environment variables and works independently of the `--metrics` flag. When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, the server exports traces via OTLP\u002FgRPC:\n\n```bash\n# Send traces to a local Tempo instance\nOTEL_EXPORTER_OTLP_ENDPOINT=http:\u002F\u002Flocalhost:4317 \\\nOTEL_EXPORTER_OTLP_INSECURE=true \\\n.\u002Fmcp-grafana -t streamable-http\n\n# Send traces to Grafana Cloud with authentication\nOTEL_EXPORTER_OTLP_ENDPOINT=https:\u002F\u002Ftempo-us-central1.grafana.net:443 \\\nOTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Basic ...\" \\\n.\u002Fmcp-grafana -t streamable-http\n```\n\nTool call spans follow semconv naming (`tools\u002Fcall \u003Ctool_name>`) and include attributes like `gen_ai.tool.name`, `mcp.method.name`, and `mcp.session.id`. The server also supports W3C trace context propagation from the `_meta` field of tool call requests.\n\n**Docker example with metrics and tracing:**\n\n```bash\ndocker run --rm -p 8000:8000 \\\n -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 \\\n -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour token> \\\n -e OTEL_EXPORTER_OTLP_ENDPOINT=http:\u002F\u002Ftempo:4317 \\\n -e OTEL_EXPORTER_OTLP_INSECURE=true \\\n grafana\u002Fmcp-grafana \\\n -t streamable-http --metrics\n```\n\n## Troubleshooting\n\n### Grafana Version Compatibility\n\nIf you encounter the following error when using datasource-related tools:\n\n```\nget datasource by uid : [GET \u002Fdatasources\u002Fuid\u002F{uid}][400] getDataSourceByUidBadRequest {\"message\":\"id is invalid\"}\n```\n\nThis typically indicates that you are using a Grafana version earlier than 9.0. The `\u002Fdatasources\u002Fuid\u002F{uid}` API endpoint was introduced in Grafana 9.0, and datasource operations will fail on earlier versions.\n\n**Solution:** Upgrade your Grafana instance to version 9.0 or later to resolve this issue.\n\n## Development\n\nContributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.\n\nThis project is written in Go. Install Go following the instructions for your platform.\n\nTo run the server locally in STDIO mode (which is the default for local development), use:\n\n```bash\nmake run\n```\n\nTo run the server locally in SSE mode, use:\n\n```bash\ngo run .\u002Fcmd\u002Fmcp-grafana --transport sse\n```\n\nYou can also run the server using the SSE transport inside a custom built Docker image. Just like the published Docker image, this custom image's entrypoint defaults to SSE mode. To build the image, use:\n\n```\nmake build-image\n```\n\nAnd to run the image in SSE mode (the default), use:\n\n```\ndocker run -it --rm -p 8000:8000 mcp-grafana:latest\n```\n\nIf you need to run it in STDIO mode instead, override the transport setting:\n\n```\ndocker run -it --rm mcp-grafana:latest -t stdio\n```\n\n### Testing\n\nThere are three types of tests available:\n\n1. Unit Tests (no external dependencies required):\n\n```bash\nmake test-unit\n```\n\nYou can also run unit tests with:\n\n```bash\nmake test\n```\n\n2. Integration Tests (requires docker containers to be up and running):\n\n```bash\nmake test-integration\n```\n\n3. Cloud Tests (requires cloud Grafana instance and credentials):\n\n```bash\nmake test-cloud\n```\n\n> Note: Cloud tests are automatically configured in CI. For local development, you'll need to set up your own Grafana Cloud instance and credentials.\n\nMore comprehensive integration tests will require a Grafana instance to be running locally on port 3000; you can start one with Docker Compose:\n\n```bash\ndocker-compose up -d\n```\n\nThe integration tests can be run with:\n\n```bash\nmake test-all\n```\n\nIf you're adding more tools, please add integration tests for them. The existing tests should be a good starting point.\n\n### Linting\n\nTo lint the code, run:\n\n```bash\nmake lint\n```\n\nThis includes a custom linter that checks for unescaped commas in `jsonschema` struct tags. The commas in `description` fields must be escaped with `\\\\,` to prevent silent truncation. You can run just this linter with:\n\n```bash\nmake lint-jsonschema\n```\n\nSee the [JSONSchema Linter documentation](internal\u002Flinter\u002Fjsonschema\u002FREADME.md) for more details.\n\n## License\n\nThis project is licensed under the [Apache License, Version 2.0](LICENSE).\n\n[mcp]: https:\u002F\u002Fmodelcontextprotocol.io\u002F\n[service-account]: https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Fadministration\u002Fservice-accounts\u002F#add-a-token-to-a-service-account-in-grafana\n","# Grafana MCP 服务器\n\n[![单元测试](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Funit.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Funit.yml)\n[![集成测试](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fintegration.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fintegration.yml)\n[![端到端测试](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fe2e.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Factions\u002Fworkflows\u002Fe2e.yml)\n[![Go 参考文档](https:\u002F\u002Fpkg.go.dev\u002Fbadge\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana.svg)](https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana)\n[![MCP 目录](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgrafana_mcp-grafana_readme_5dfccc754b71.png)](https:\u002F\u002Farchestra.ai\u002Fmcp-catalog\u002Fgrafana__mcp-grafana)\n\n一个用于 Grafana 的 [模型上下文协议][mcp] (MCP) 服务器。\n\n这提供了对您的 Grafana 实例及其周边生态系统的访问权限。\n\n## 快速入门\n\n需要 [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F)。将以下内容添加到您的 MCP 客户端配置中（例如 Claude Desktop、Cursor）：\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-grafana\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003C您的服务账号令牌>\"\n }\n }\n }\n}\n```\n\n对于 Grafana Cloud，请将 `GRAFANA_URL` 替换为您的实例 URL（例如 `https:\u002F\u002Fmyinstance.grafana.net`）。有关更多安装选项，包括 Docker、二进制文件和 Helm，请参阅 [使用方法](#usage)。\n\n## 要求\n\n- 需要 **Grafana 9.0 或更高版本** 才能实现完整功能。某些功能，尤其是与数据源相关的操作，在较早版本中可能无法正常工作，因为缺少 API 端点。\n\n## 功能\n\n_以下功能目前在 MCP 服务器中可用。此列表仅供参考，并不构成未来功能的路线图或承诺。_\n\n### 仪表板\n\n- **搜索仪表板：** 按标题或其他元数据查找仪表板\n- **按 UID 获取仪表板：** 使用其唯一标识符获取完整的仪表板详情。_警告：大型仪表板会占用大量上下文窗口空间。_\n- **获取仪表板摘要：** 获取仪表板的简洁概览，包括标题、面板数量、面板类型、变量和元数据，而无需完整的 JSON，以最大限度减少上下文窗口的使用\n- **获取仪表板属性：** 使用 JSONPath 表达式提取仪表板的特定部分（例如 `$.title`、`$.panels[*].title`），仅获取所需数据，从而减少上下文窗口的消耗\n- **更新或创建仪表板：** 修改现有仪表板或创建新仪表板。_警告：需要完整的仪表板 JSON，这可能会占用大量的上下文窗口空间。_\n- **修补仪表板：** 对仪表板应用特定更改，而无需完整的 JSON，从而显著减少针对目标修改时的上下文窗口使用\n- **获取面板查询和数据源信息：** 从仪表板中的每个面板获取标题、查询字符串以及数据源信息（包括 UID 和类型，如果可用）\n\n### 运行面板查询\n\n> **注意：** 运行面板查询工具 **默认已禁用**。要启用它们，请将 `runpanelquery` 添加到您的 `--enabled-tools` 标志中。\n\n- **运行面板查询：** 使用自定义时间范围和变量覆盖执行仪表板面板的查询。\n\n#### 上下文窗口管理\n\n仪表板工具现在包含几种有效管理上下文窗口使用的方法（[问题 #101](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F101))：\n\n- **使用 `get_dashboard_summary`** 获取仪表板概述并规划修改\n- **使用 `get_dashboard_property`** 结合 JSONPath，仅在需要仪表板特定部分时使用\n- **避免使用 `get_dashboard_by_uid`**，除非您确实需要完整的仪表板 JSON\n\n### 数据源\n\n- **列出并获取数据源信息：** 查看所有已配置的数据源，并检索每个数据源的详细信息。\n - _支持的数据源类型：Prometheus、Loki、ClickHouse、CloudWatch、Elasticsearch。_\n\n### 查询示例\n\n> **注意：** 查询示例工具 **默认已禁用**。要启用它们，请将 `examples` 添加到您的 `--enabled-tools` 标志中。\n\n- **获取查询示例：** 检索不同数据源类型的查询示例，以学习查询语法。\n\n### Prometheus 查询\n\n- **查询 Prometheus：** 对 Prometheus 数据源执行 PromQL 查询（支持即时和范围指标查询）。\n- **查询 Prometheus 元数据：** 从 Prometheus 数据源检索指标元数据、指标名称、标签名称和标签值。\n- **查询直方图百分位数：** 使用 histogram_quantile 计算直方图百分位数（p50、p90、p95、p99）。\n\n### Loki 查询\n\n- **查询 Loki 日志和指标：** 使用 LogQL 对 Loki 数据源执行日志查询和指标查询。\n- **查询 Loki 元数据：** 从 Loki 数据源检索标签名称、标签值和流统计信息。\n- **查询 Loki 模式：** 检索 Loki 检测到的日志模式，以识别常见的日志结构和异常。\n\n### ClickHouse 查询\n\n> **注意：** ClickHouse 工具 **默认已禁用**。要启用它们，请将 `clickhouse` 添加到您的 `--enabled-tools` 标志中。\n\n- **列出 ClickHouse 表：** 列出 ClickHouse 数据库中的所有表，并显示行数和大小。\n- **描述表结构：** 获取 ClickHouse 表的列名、类型和元数据。\n- **查询 ClickHouse：** 执行 SQL 查询，支持 Grafana 宏和变量替换。\n\n### CloudWatch 查询\n\n> **注意：** CloudWatch 工具 **默认已禁用**。要启用它们，请将 `cloudwatch` 添加到您的 `--enabled-tools` 标志中。\n\n- **列出 CloudWatch 命名空间：** 发现可用的 AWS CloudWatch 命名空间。\n- **列出 CloudWatch 指标：** 列出特定命名空间中的可用指标。\n- **列出 CloudWatch 维度：** 获取用于筛选指标查询的维度。\n- **查询 CloudWatch：** 执行 CloudWatch 指标查询，并支持时间范围选择。\n\n### 日志搜索\n\n> **注意：** 搜索日志工具 **默认已禁用**。要启用它们，请将 `searchlogs` 添加到您的 `--enabled-tools` 标志中。\n\n- **搜索日志：** 在 ClickHouse（OTel 格式）和 Loki 数据源中进行高级日志搜索。\n\n### Elasticsearch 查询\n\n> **注意：** Elasticsearch 工具 **默认已禁用**。要启用它们，请将 `elasticsearch` 添加到您的 `--enabled-tools` 标志中。\n\n- **查询 Elasticsearch：** 使用 Lucene 查询语法或 Elasticsearch Query DSL 对 Elasticsearch 数据源执行搜索查询。支持按时间范围过滤，并可检索日志、指标或其他已索引的数据。返回包含索引、ID、源字段以及可选相关性得分的文档。\n\n### 事件\n\n- **搜索、创建和更新事件：** 管理 Grafana Incident 中的事件，包括搜索、创建以及向事件添加活动。\n\n### Sift 调查\n\n- **列出 Sift 调查：** 检索 Sift 调查列表，并支持 limit 参数。\n- **获取 Sift 调查：** 通过 UUID 检索特定 Sift 调查的详细信息。\n- **获取 Sift 分析：** 从 Sift 调查中检索特定分析。\n- **查找日志中的错误模式：** 使用 Sift 检测 Loki 日志中的异常错误模式。\n- **查找慢请求：** 使用 Sift（Tempo）检测慢请求。\n\n### 告警\n\n- **列出并获取告警规则信息：** 在 Grafana 中查看告警规则及其状态（触发中\u002F正常\u002F出错等）。支持 Grafana 管理的规则以及来自 Prometheus 或 Loki 数据源的由数据源管理的规则。\n- **创建和更新告警规则：** 创建新的告警规则或修改现有规则。\n- **删除告警规则：** 根据 UID 删除告警规则。\n- **管理告警路由：** 查看通知策略、联系点和时间间隔。支持 Grafana 管理的联系点以及来自外部 Alertmanager 数据源（Prometheus Alertmanager、Mimir、Cortex）的接收器。\n\n### Grafana OnCall\n\n- **列出和管理排班：** 在 Grafana OnCall 中查看和管理值班排班。\n- **获取班次详情：** 检索特定值班班次的详细信息。\n- **获取当前值班用户：** 查看某个排班中当前正在值班的用户。\n- **列出团队和用户：** 查看所有 OnCall 团队和用户。\n- **列出告警组：** 根据状态、集成、标签和时间范围等多种条件，在 Grafana OnCall 中查看和筛选告警组。\n- **获取告警组详情：** 根据告警组 ID 检索其详细信息。\n\n### 管理员\n\n> **注意：** 管理员工具默认处于禁用状态。如需启用，请在 `--enabled-tools` 标志中包含 `admin`。\n- **列出团队：** 查看 Grafana 中所有已配置的团队。\n- **列出用户：** 查看 Grafana 组织中的所有用户。\n- **列出所有角色：** 列出所有 Grafana 角色，可选择性地筛选可委派的角色。\n- **获取角色详情：** 根据 UID 获取特定 Grafana 角色的详细信息。\n- **列出角色的分配对象：** 列出被分配给某角色的所有用户、团队和服务账户。\n- **列出用户的角色：** 列出一个或多个用户所被分配的所有角色。\n- **列出团队的角色：** 列出一个或多个团队所被分配的所有角色。\n- **列出资源的权限：** 列出为特定资源（仪表板、数据源、文件夹等）定义的所有权限。\n- **描述 Grafana 资源：** 列出某一资源类型可用的权限及分配能力。\n\n### 导航\n\n- **生成深度链接：** 为 Grafana 资源创建准确的深度链接 URL，而非依赖大语言模型猜测 URL。\n - **仪表板链接：** 使用仪表板的 UID 生成直接链接（例如：`http:\u002F\u002Flocalhost:3000\u002Fd\u002Fdashboard-uid`）。\n - **面板链接：** 使用 viewPanel 参数创建指向仪表板中特定面板的链接（例如：`http:\u002F\u002Flocalhost:3000\u002Fd\u002Fdashboard-uid?viewPanel=5`）。\n - **Explore 链接：** 生成带有预配置数据源的 Grafana Explore 链接（例如：`http:\u002F\u002Flocalhost:3000\u002Fexplore?left={\"datasource\":\"prometheus-uid\"}`）。\n - **时间范围支持：** 可在链接中添加时间范围参数（`from=now-1h&to=now`）。\n - **自定义参数：** 包括仪表板变量或刷新间隔等其他查询参数。\n\n### 注释\n\n- **获取注释：** 使用过滤器查询注释。支持时间范围、仪表板 UID、标签和匹配模式。\n- **创建注释：** 在仪表板或面板上创建新注释。\n- **创建 Graphite 注释：** 使用 Graphite 格式创建注释（内容、时间、标签、数据）。\n- **更新注释：** 替换现有注释的所有字段（完全更新）。\n- **部分更新注释：** 仅更新注释的特定字段（部分更新）。\n- **获取注释标签：** 列出可用的注释标签，并可选择性地进行筛选。\n\n### 渲染\n\n- **获取面板或仪表板图像：** 将 Grafana 仪表板的某个面板或整个仪表板渲染为 PNG 图像。返回 Base64 编码的数据，可用于报告、告警或演示文稿中。支持自定义尺寸、时间范围、主题、缩放比例以及仪表板变量。\n - _注意：需要安装并配置 [Grafana 图像渲染服务](https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Fsetup-grafana\u002Fimage-rendering\u002F)。_\n\n工具列表是可配置的，因此您可以选择哪些工具对 MCP 客户端可用。\n如果您不使用某些功能，或者不想占用过多的上下文窗口，这将非常有用。\n要禁用某一类工具，可以在启动服务器时使用 `--disable-\u003Ccategory>` 标志。例如，要禁用 OnCall 工具，可以使用 `--disable-oncall`；要禁用导航深度链接生成功能，则使用 `--disable-navigation`。\n\n\n#### RBAC 权限\n\n每个工具都需要特定的 RBAC 权限才能正常运行。在为 MCP 服务器创建服务账户时，请确保其具有根据您计划使用的工具而定的必要权限。列出的权限是最低要求的操作——根据您的使用场景，您可能还需要适当的范围（例如 `datasources:*`、`dashboards:*`、`folders:*`）。\n\n提示：如果您不熟悉 Grafana 的 RBAC，或者希望采用更快速简单的设置方式，而不是配置许多细粒度的范围，您可以将内置角色如“编辑者”分配给服务账户。“编辑者”角色授予广泛的读写权限，能够支持大多数 MCP 服务器操作；它不如手动应用的范围那样细粒度（因此限制性也较低），所以仅当便利性比严格的最小权限原则更重要时才使用。\n\n**注意：** Grafana Incident 和 Sift 工具使用基本的 Grafana 角色，而非细粒度的 RBAC 权限：\n- **查看者角色：** 需用于只读操作（列出事件、获取调查）\n- **编辑者角色：** 需用于写操作（创建事件、修改调查）\n\n有关 Grafana RBAC 的更多信息，请参阅[官方文档](https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Fadministration\u002Froles-and-permissions\u002Faccess-control\u002F)。\n\n#### RBAC 范围\n\n范围定义了权限所适用的具体资源。每项操作都需要合适的权限与范围组合。\n\n**常见范围模式：**\n\n- **广泛访问：** 使用 `*` 通配符以获得组织范围内的访问权限\n\n - `datasources:*` - 访问所有数据源\n - `dashboards:*` - 访问所有仪表板\n - `folders:*` - 访问所有文件夹\n - `teams:*` - 访问所有团队\n\n- **有限访问：** 使用具体的 UID 或 ID 来限制对单个资源的访问\n - `datasources:uid:prometheus-uid` - 仅访问特定的 Prometheus 数据源\n - `dashboards:uid:abc123` - 仅访问 UID 为 `abc123` 的仪表板\n - `folders:uid:xyz789` - 仅访问 UID 为 `xyz789` 的文件夹\n - `teams:id:5` - 仅访问 ID 为 `5` 的团队\n - `global.users:id:123` - 仅访问 ID 为 `123` 的用户\n\n**示例：**\n\n- **MCP 服务器完全访问权限：** 授予所有工具的广泛权限\n\n ```\n datasources:* (datasources:read, datasources:query)\n dashboards:* (dashboards:read, dashboards:create, dashboards:write)\n folders:* (用于仪表板创建和告警规则)\n teams:* (teams:read)\n global.users:* (users:read)\n ```\n\n- **有限数据源访问权限：** 仅查询特定的 Prometheus 和 Loki 实例\n\n ```\n datasources:uid:prometheus-prod (datasources:query)\n datasources:uid:loki-prod (datasources:query)\n ```\n\n- **仪表板特定访问权限：** 仅读取特定的仪表板\n ```\n dashboards:uid:monitoring-dashboard (dashboards:read)\n dashboards:uid:alerts-dashboard (dashboards:read)\n ```\n\n### 工具\n\n| 工具 | 类别 | 描述 | 必需的 RBAC 权限 | 必需的作用域 |\n| --------------------------------- | ----------- | ------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------- |\n| `list_teams` | 管理员 | 列出所有团队 | `teams:read` | `teams:*` 或 `teams:id:1` |\n| `list_users_by_org` | 管理员 | 列出组织中的所有用户 | `users:read` | `global.users:*` 或 `global.users:id:123` |\n| `list_all_roles` | 管理员 | 列出所有 Grafana 角色 | `roles:read` | `roles:*` |\n| `get_role_details` | 管理员 | 获取 Grafana 角色的详细信息 | `roles:read` | `roles:uid:editor` |\n| `get_role_assignments` | 管理员 | 列出某个角色的分配情况 | `roles:read` | `roles:uid:editor` |\n| `list_user_roles` | 管理员 | 列出用户的角色 | `roles:read` | `global.users:id:123` |\n| `list_team_roles` | 管理员 | 列出团队的角色 | `roles:read` | `teams:id:7` |\n| `get_resource_permissions`| 管理员 | 列出某个资源的权限 | `permissions:read` | `dashboards:uid:abcd1234` |\n| `get_resource_description`| 管理员 | 描述一个 Grafana 资源类型 | `permissions:read` | `dashboards:*` |\n| `search_dashboards` | 搜索 | 搜索仪表板 | `dashboards:read` | `dashboards:*` 或 `dashboards:uid:abc123` |\n| `get_dashboard_by_uid` | 仪表板 | 根据 UID 获取仪表板 | `dashboards:read` | `dashboards:uid:abc123` |\n| `update_dashboard` | 仪表板 | 更新或创建新的仪表板 | `dashboards:create`, `dashboards:write` | `dashboards:*`, `folders:*` 或 `folders:uid:xyz789` |\n| `get_dashboard_panel_queries` | 仪表板 | 从仪表板中获取面板标题、查询、数据源 UID 和类型 | `dashboards:read` | `dashboards:uid:abc123` |\n| `run_panel_query` | RunPanelQuery* | 执行一个或多个仪表板面板查询 | `dashboards:read`, `datasources:query` | `dashboards:uid:*`, `datasources:uid:*` |\n| `get_dashboard_property` | 仪表板 | 使用 JSONPath 表达式提取仪表板的特定部分 | `dashboards:read` | `dashboards:uid:abc123` |\n| `get_dashboard_summary` | 仪表板 | 获取仪表板的精简摘要，不含完整 JSON | `dashboards:read` | `dashboards:uid:abc123` |\n| `list_datasources` | 数据源 | 列出数据源 | `datasources:read` | `datasources:*` |\n| `get_datasource` | 数据源 | 根据 UID 或名称获取数据源 | `datasources:read` | `datasources:uid:prometheus-uid` |\n| `get_query_examples` | 示例* | 获取某种数据源类型的示例查询 | `datasources:read` | `datasources:*` |\n| `query_prometheus` | Prometheus | 对 Prometheus 数据源执行查询 | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_metric_metadata` | Prometheus | 列出指标元数据 | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_metric_names` | Prometheus | 列出可用的指标名称 | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_label_names` | Prometheus | 列出与选择器匹配的标签名称 | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_prometheus_label_values` | Prometheus | 列出特定标签的值 | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `query_prometheus_histogram` | Prometheus | 计算直方图百分位数值 | `datasources:query` | `datasources:uid:prometheus-uid` |\n| `list_incidents` | 事件 | 列出 Grafana Incident 中的事件 | 查看者角色 | 无 |\n| `create_incident` | 事件 | 在 Grafana Incident 中创建事件 | 编辑者角色 | 无 |\n| `add_activity_to_incident` | 事件 | 向 Grafana Incident 中的事件添加活动项目 | 编辑者角色 | 无 |\n| `get_incident` | 事件 | 根据 ID 获取单个事件 | 查看者角色 | 无 |\n| `query_loki_logs` | Loki | 使用 LogQL 查询并检索日志（日志或指标查询） | `datasources:query` | `datasources:uid:loki-uid` |\n| `list_loki_label_names` | Loki | 列出日志中所有可用的标签名称 | `datasources:query` | `datasources:uid:loki-uid` |\n| `list_loki_label_values` | Loki | 列出特定日志标签的值 | `datasources:query` | `datasources:uid:loki-uid` |\n| `query_loki_stats` | Loki | 获取有关日志流的统计信息 | `datasources:query` | `datasources:uid:loki-uid` |\n| `query_loki_patterns` | Loki | 查询检测到的日志模式以识别常见结构 | `datasources:query` | `datasources:uid:loki-uid` |\n| `list_clickhouse_tables` | ClickHouse* | 列出 ClickHouse 数据库中的表 | `datasources:query` | `datasources:uid:*` |\n| `describe_clickhouse_table` | ClickHouse* | 获取包含列类型的表结构 | `datasources:query` | `datasources:uid:*` |\n| `query_clickhouse` | ClickHouse* | 执行带有宏替换的 SQL 查询 | `datasources:query` | `datasources:uid:*` |\n| `list_cloudwatch_namespaces` | CloudWatch* | 列出可用的 AWS CloudWatch 命名空间 | `datasources:query` | `datasources:uid:*` |\n| `list_cloudwatch_metrics` | CloudWatch* | 列出命名空间中的指标 | `datasources:query` | `datasources:uid:*` |\n| `list_cloudwatch_dimensions` | CloudWatch* | 列出指标的维度 | `datasources:query` | `datasources:uid:*` |\n| `query_cloudwatch` | CloudWatch* | 执行 CloudWatch 指标查询 | `datasources:query` | `datasources:uid:*` |\n| `search_logs` | SearchLogs* | 在 ClickHouse 和 Loki 中跨日志进行搜索 | `datasources:query` | `datasources:uid:*` |\n| `query_elasticsearch` | Elasticsearch* | 使用 Lucene 语法或 Query DSL 查询 Elasticsearch | `datasources:query` | `datasources:uid:elasticsearch-uid` |\n| `alerting_manage_rules` | 警报 | 管理警报规则（列出、获取、版本、创建、更新、删除） | `alert.rules:read` + `alert.rules:write` 用于变更操作 | `folders:*` 或 `folders:uid:alerts-folder` |\n| `alerting_manage_routing` | 警报 | 管理通知策略、联系点和时间间隔 | `alert.notifications:read` | 全局范围 |\n| `list_oncall_schedules` | 待命 | 列出 Grafana OnCall 中的排班计划 | `grafana-oncall-app.schedules:read` | 插件特定的作用域 |\n| `get_oncall_shift` | 待命 | 获取特定待命班次的详细信息 | `grafana-oncall-app.schedules:read` | 插件特定的作用域 |\n| `get_current_oncall_users` | 待命 | 获取当前为特定排班计划待命的用户 | `grafana-oncall-app.schedules:read` | 插件特定的作用域 |\n| `list_oncall_teams` | 待命 | 列出 Grafana OnCall 中的团队 | `grafana-oncall-app.user-settings:read` | 插件特定的作用域 |\n| `list_oncall_users` | 待命 | 列出 Grafana OnCall 中的用户 | `grafana-oncall-app.user-settings:read` | 插件特定的作用域 |\n| `list_alert_groups` | 待命 | 列出 Grafana OnCall 中的告警组，并提供筛选选项 | `grafana-oncall-app.alert-groups:read` | 插件特定的作用域 |\n| `get_alert_group` | 待命 | 根据 ID 获取 Grafana OnCall 中的特定告警组 | `grafana-oncall-app.alert-groups:read` | 插件特定的作用域 |\n| `get_sift_investigation` | Sift | 根据 UUID 检索现有的 Sift 调查 | 查看者角色 | 无 |\n| `get_sift_analysis` | Sift | 从 Sift 调查中检索特定分析 | 查看者角色 | 无 |\n| `list_sift_investigations` | Sift | 检索 Sift 调查列表，可选设置限制 | 查看者角色 | 无 |\n| `find_error_pattern_logs` | Sift | 在 Loki 日志中查找异常高的错误模式。 | 编辑者角色 | 无 |\n| `find_slow_requests` | Sift | 从相关 Tempo 数据源中查找慢请求。 | 编辑者角色 | 无 |\n| `list_pyroscope_label_names` | Pyroscope | 列出与选择器匹配的标签名称 | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `list_pyroscope_label_values` | Pyroscope | 列出与标签名称选择器匹配的标签值 | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `list_pyroscope_profile_types` | Pyroscope | 列出可用的性能剖析类型 | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `fetch_pyroscope_profile` | Pyroscope | 以 DOT 格式获取性能剖析文件以便分析 | `datasources:query` | `datasources:uid:pyroscope-uid` |\n| `get_assertions` | Asserts | 获取给定实体的断言摘要 | 插件特定的权限 | 插件特定的作用域 |\n| `generate_deeplink` | 导航 | 为 Grafana 资源生成准确的深层链接 URL | 无（仅读取 URL 的生成） | 无 |\n| `get_annotations` | 注释 | 使用过滤器获取注释 | `annotations:read` | `annotations:*` 或 `annotations:id:123` |\n| `create_annotation` | 注释 | 创建新的注释（标准格式或 Graphite 格式） | `annotations:write` | `annotations:*` |\n| `update_annotation` | 注释 | 更新注释的特定字段（部分更新） | `annotations:write` | `annotations:*` |\n| `get_annotation_tags` | 注释 | 列出注释标签，可选进行过滤 | `annotations:read` | `annotations:*` |\n| `get_panel_image` | 渲染 | 将仪表板面板或整个仪表板渲染为 PNG 图像 | `dashboards:read` | `dashboards:uid:abc123` |\n\n_* 默认禁用。将类别添加到 `--enabled-tools` 以启用。_*\n\n## CLI 标志参考\n\n`mcp-grafana` 二进制文件支持多种命令行标志来进行配置：\n\n**传输选项：**\n- `-t, --transport`: 传输类型（`stdio`、`sse` 或 `streamable-http`）- 默认值：`stdio`\n- `--address`: SSE\u002Fstreamable-http 服务器的主机和端口 - 默认值：`localhost:8000`\n- `--base-path`: SSE\u002Fstreamable-http 服务器的基础路径\n- `--endpoint-path`: streamable-http 服务器的端点路径 - 默认值：`\u002F`\n\n**调试与日志记录：**\n- `--debug`: 启用调试模式，以获取详细的 HTTP 请求\u002F响应日志\n- `--log-level`: 日志级别（`debug`、`info`、`warn`、`error`）- 默认值：`info`\n\n**可观测性：**\n- `--metrics`: 在 `\u002Fmetrics` 启用 Prometheus 指标端点\n- `--metrics-address`: 指标服务器的独立地址（例如 `:9090`）。如果为空，则指标将在主服务器上提供。\n\n**会话管理：**\n- `--session-idle-timeout-minutes`: 会话空闲超时时间，单位为分钟。在此期间无活动的会话将被自动回收 - 默认值：`30` 分钟。设置为 `0` 可禁用会话回收。仅适用于 SSE 和 streamable-http 传输。\n\n**工具配置：**\n- `--enabled-tools`: 以逗号分隔的已启用类别列表 - 默认值：除 `admin` 外的所有类别；若要启用管理工具，需将 `admin` 添加到列表中（例如 `\"search,datasource,...,admin\"`）\n- `--max-loki-log-limit`: 每次调用 `query_loki_logs` 返回的最大日志行数 - 默认值：`100` 行。注意：此值应至少比 Loki 服务器端的 `max_entries_limit_per_query` 少 1，以便检测数据是否被截断（该工具内部会请求 `limit+1` 行，以判断是否存在更多数据）。\n- `--disable-search`: 禁用搜索工具\n- `--disable-datasource`: 禁用数据源工具\n- `--disable-incident`: 禁用事件工具\n- `--disable-prometheus`: 禁用 Prometheus 工具\n- `--disable-write`: 禁用写入工具（创建\u002F更新操作）\n- `--disable-loki`: 禁用 Loki 工具\n- `--disable-elasticsearch`: 禁用 Elasticsearch 工具\n- `--disable-alerting`: 禁用告警工具\n- `--disable-dashboard`: 禁用仪表板工具\n- `--disable-oncall`: 禁用值班工具\n- `--disable-asserts`: 禁用断言工具\n- `--disable-sift`: 禁用 Sift 工具\n- `--disable-admin`: 禁用管理工具\n- `--disable-pyroscope`: 禁用 Pyroscope 工具\n- `--disable-navigation`: 禁用导航工具\n- `--disable-rendering`: 禁用渲染工具（面板\u002F仪表板图像导出）\n- `--disable-cloudwatch`: 禁用 CloudWatch 工具\n- `--disable-examples`: 禁用查询示例工具\n- `--disable-clickhouse`: 禁用 ClickHouse 工具\n- `--disable-searchlogs`: 禁用 search_logs 工具\n- `--disable-runpanelquery`: 禁用运行面板查询工具\n\n### 只读模式\n\n`--disable-write` 标志提供了一种以只读模式运行 MCP 服务器的方式，从而防止对您的 Grafana 实例进行任何写入操作。这在以下场景中非常有用：\n\n- 使用具有有限只读权限的服务账户\n- 向 AI 助手提供可观测性数据，但不赋予其修改能力\n- 在生产环境中运行，需要限制写入访问\n- 测试和开发场景中，希望防止意外修改\n\n当启用 `--disable-write` 时，以下写入操作将被禁用：\n\n**仪表板工具：**\n- `update_dashboard`\n\n**文件夹工具：**\n- `create_folder`\n\n**事件工具：**\n- `create_incident`\n- `add_activity_to_incident`\n\n**告警工具：**\n- `alerting_manage_rules`（创建、更新、删除操作）\n\n**注释工具：**\n- `create_annotation`\n- `update_annotation`\n\n**Sift 工具：**\n- `find_error_pattern_logs`（创建调查）\n- `find_slow_requests`（创建调查）\n\n所有读取操作仍然可用，允许您查询仪表板、运行 PromQL\u002FLogQL 查询、列出资源并检索数据。\n\n**客户端 TLS 配置（用于 Grafana 连接）：**\n- `--tls-cert-file`: 客户端身份验证的 TLS 证书文件路径\n- `--tls-key-file`: 客户端身份验证的 TLS 私钥文件路径\n- `--tls-ca-file`: 用于服务器验证的 TLS CA 证书文件路径\n- `--tls-skip-verify`: 跳过 TLS 证书验证（不安全）\n\n**服务器 TLS 配置（仅限 streamable-http 传输）：**\n- `--server.tls-cert-file`: 用于服务器 HTTPS 的 TLS 证书文件路径\n- `--server.tls-key-file`: 用于服务器 HTTPS 的 TLS 私钥文件路径\n\n## 使用方法\n\n此 MCP 服务器既可用于本地 Grafana 实例，也可用于 Grafana Cloud。对于 Grafana Cloud，请在下面的配置示例中使用您的实例 URL（例如 `https:\u002F\u002Fmyinstance.grafana.net`），而不是 `http:\u002F\u002Flocalhost:3000`。\n\n1. 如果使用服务账户令牌认证，请在 Grafana 中创建一个具有足够权限以使用所需工具的服务账户，\n 生成服务账户令牌，并将其复制到剪贴板，以便在配置文件中使用。\n 有关创建服务账户令牌的详细信息，请参阅 [Grafana 服务账户文档][service-account]。\n 提示：如果您不熟悉配置细粒度的 RBAC 范围，一个更简单（但权限限制较少）的选择是将内置的 `Editor` 角色分配给服务账户。这将授予广泛的读写权限，涵盖大多数 MCP 服务器操作——当便利性高于严格的最小权限原则时，可以使用此方法。\n\n > **注意：** 环境变量 `GRAFANA_API_KEY` 已弃用，将在未来版本中移除。请改用 `GRAFANA_SERVICE_ACCOUNT_TOKEN`。旧变量名将继续工作以保持向后兼容性，但会显示弃用警告。\n\n### 多组织支持\n\n您可以使用以下任一方式指定要交互的组织：\n\n- **环境变量：** 将 `GRAFANA_ORG_ID` 设置为数字形式的组织 ID\n- **HTTP 头：** 使用 SSE 或 streamable HTTP 传输时，设置 `X-Grafana-Org-Id` 头（头优先于环境变量，这意味着您可以同时设置默认组织）。\n\n当提供组织 ID 时，MCP 服务器会在所有发送到 Grafana 的请求中设置 `X-Grafana-Org-Id` 头，从而确保操作在指定组织上下文中执行。\n\n**带有组织 ID 的示例：**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_USERNAME\": \"\u003Cyour username>\",\n \"GRAFANA_PASSWORD\": \"\u003Cyour password>\",\n \"GRAFANA_ORG_ID\": \"2\"\n }\n }\n }\n}\n```\n\n### 自定义 HTTP 头\n\n你可以使用 `GRAFANA_EXTRA_HEADERS` 环境变量为所有 Grafana API 请求添加任意 HTTP 头。该值应为一个 JSON 对象，将头名称映射到对应的值。\n\n**带有自定义头的示例：**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour token>\",\n \"GRAFANA_EXTRA_HEADERS\": \"{\\\"X-Custom-Header\\\": \\\"custom-value\\\", \\\"X-Tenant-ID\\\": \\\"tenant-123\\\"}\"\n }\n }\n }\n}\n```\n\n2. 您有多种方式可以安装 `mcp-grafana`：\n\n - **uvx（推荐）**：如果您已安装 [uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F)，则无需额外设置——`uvx` 会自动下载并运行服务器：\n\n ```bash\n uvx mcp-grafana\n ```\n\n - **Docker 镜像**：使用 Docker Hub 上的预构建 Docker 镜像。\n\n **重要提示**：Docker 镜像的入口点默认配置为以 SSE 模式运行 MCP 服务器，但大多数用户希望使用 STDIO 模式，以便与 Claude Desktop 等 AI 助手直接集成：\n\n 1. **STDIO 模式**：对于 stdio 模式，您必须显式地通过 `-t stdio` 覆盖默认设置，并包含 `-i` 标志以保持标准输入打开：\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n # 对于本地 Grafana：\n docker run --rm -i -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana -t stdio\n # 对于 Grafana Cloud：\n docker run --rm -i -e GRAFANA_URL=https:\u002F\u002Fmyinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana -t stdio\n ```\n\n 2. **SSE 模式**：在此模式下，服务器作为客户端连接的 HTTP 服务器运行。您必须使用 `-p` 标志暴露 8000 端口：\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n docker run --rm -p 8000:8000 -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana\n ```\n\n 3. **可流式 HTTP 模式**：在此模式下，服务器作为一个独立进程运行，可以处理多个客户端连接。您必须使用 `-p` 标志暴露 8000 端口：对于此模式，您必须显式地通过 `-t streamable-http` 覆盖默认设置。\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n docker run --rm -p 8000:8000 -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> grafana\u002Fmcp-grafana -t streamable-http\n ```\n\n 对于带有服务器 TLS 证书的 HTTPS 可流式 HTTP 模式：\n\n ```bash\n docker pull grafana\u002Fmcp-grafana\n docker run --rm -p 8443:8443 \\\n -v \u002Fpath\u002Fto\u002Fcerts:\u002Fcerts:ro \\\n -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 \\\n -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour service account token> \\\n grafana\u002Fmcp-grafana \\\n -t streamable-http \\\n -addr :8443 \\\n --server.tls-cert-file \u002Fcerts\u002Fserver.crt \\\n --server.tls-key-file \u002Fcerts\u002Fserver.key\n ```\n\n - **下载二进制文件**：从 [releases 页面](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Freleases)下载最新版本的 `mcp-grafana`，并将其放置在您的 `$PATH` 中。\n\n - **从源代码构建**：如果您已安装 Go 工具链，也可以从源代码构建并安装，使用 `GOBIN` 环境变量指定二进制文件应安装的目录。该目录也应位于您的 `PATH` 中。\n\n ```bash\n GOBIN=\"$HOME\u002Fgo\u002Fbin\" go install github.com\u002Fgrafana\u002Fmcp-grafana\u002Fcmd\u002Fmcp-grafana@latest\n ```\n\n - **使用 Helm 部署到 Kubernetes**：使用 [Grafana helm-charts 仓库中的 Helm 图表](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fhelm-charts\u002Ftree\u002Fmain\u002Fcharts\u002Fgrafana-mcp)\n\n ```bash\n helm repo add grafana https:\u002F\u002Fgrafana.github.io\u002Fhelm-charts\n helm install --set grafana.apiKey=\u003CGrafana_ApiKey> --set grafana.url=\u003CGrafanaUrl> my-release grafana\u002Fgrafana-mcp\n ```\n\n\n3. 将服务器配置添加到您的客户端配置文件中。例如，对于 Claude Desktop：\n\n **如果使用 uvx：**\n\n ```json\n {\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-grafana\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n }\n ```\n\n **如果使用二进制文件：**\n\n ```json\n {\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F 或者对于 Grafana Cloud 使用 \"https:\u002F\u002Fmyinstance.grafana.net\"\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\",\n \u002F\u002F 如果使用用户名\u002F密码认证\n \"GRAFANA_USERNAME\": \"\u003Cyour username>\",\n \"GRAFANA_PASSWORD\": \"\u003Cyour password>\",\n \u002F\u002F 可选：指定组织 ID 以支持多组织\n \"GRAFANA_ORG_ID\": \"1\"\n }\n }\n }\n }\n ```\n\n > 注意：如果您在 Claude Desktop 中看到 `Error: spawn mcp-grafana ENOENT`，则需要指定 `mcp-grafana` 的完整路径。\n\n **如果使用 Docker：**\n\n ```json\n {\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"GRAFANA_URL\",\n \"-e\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\",\n \"grafana\u002Fmcp-grafana\",\n \"-t\",\n \"stdio\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F 或者对于 Grafana Cloud 使用 \"https:\u002F\u002Fmyinstance.grafana.net\"\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\",\n \u002F\u002F 如果使用用户名\u002F密码认证\n \"GRAFANA_USERNAME\": \"\u003Cyour username>\",\n \"GRAFANA_PASSWORD\": \"\u003Cyour password>\",\n \u002F\u002F 可选：指定组织 ID 以支持多组织\n \"GRAFANA_ORG_ID\": \"1\"\n }\n }\n }\n }\n ```\n\n > 注意：这里的 `-t stdio` 参数至关重要，因为它覆盖了 Docker 镜像中的默认 SSE 模式。\n\n **使用 VSCode 和远程 MCP 服务器**\n\n 如果您正在使用 VSCode 并且以 SSE 模式运行 MCP 服务器（这是在不覆盖传输方式的情况下使用 Docker 镜像时的默认设置），请确保您的 `.vscode\u002Fsettings.json` 包含以下内容：\n\n ```json\n \"mcp\": {\n \"servers\": {\n \"grafana\": {\n \"type\": \"sse\",\n \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fsse\"\n }\n }\n }\n ```\n\n 对于带有服务器 TLS 证书的 HTTPS 可流式 HTTP 模式：\n\n ```json\n \"mcp\": {\n \"servers\": {\n \"grafana\": {\n \"type\": \"sse\",\n \"url\": \"https:\u002F\u002Flocalhost:8443\u002Fsse\"\n }\n }\n }\n ```\n\n### 调试模式\n\n您可以通过在命令中添加 `-debug` 标志来启用 Grafana 传输的调试模式。这将提供 MCP 服务器与 Grafana API 之间 HTTP 请求和响应的详细日志记录，有助于故障排除。\n\n要将调试模式与 Claude Desktop 配置一起使用，请按如下方式更新您的配置：\n\n**如果使用二进制文件：**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [\"-debug\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F 或者对于 Grafana Cloud 使用 \"https:\u002F\u002Fmyinstance.grafana.net\"\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003C您的服务账户令牌>\"\n }\n }\n }\n}\n```\n\n**如果使用 Docker：**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"GRAFANA_URL\",\n \"-e\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\",\n \"grafana\u002Fmcp-grafana\",\n \"-t\",\n \"stdio\",\n \"-debug\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\", \u002F\u002F 或者对于 Grafana Cloud 使用 \"https:\u002F\u002Fmyinstance.grafana.net\"\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003C您的服务账户令牌>\"\n }\n }\n }\n}\n```\n\n> 注意：与标准配置相同，`-t stdio` 参数是必需的，用于覆盖 Docker 镜像中的默认 SSE 模式。\n\n### TLS 配置\n\n如果您的 Grafana 实例位于 mTLS 之后，或者需要自定义 TLS 证书，您可以配置 MCP 服务器以使用自定义证书。该服务器支持以下 TLS 配置选项：\n\n- `--tls-cert-file`：用于客户端身份验证的 TLS 证书文件路径\n- `--tls-key-file`：用于客户端身份验证的 TLS 私钥文件路径\n- `--tls-ca-file`：用于服务器验证的 TLS CA 证书文件路径\n- `--tls-skip-verify`：跳过 TLS 证书验证（不安全，仅用于测试）\n\n**使用客户端证书身份验证的示例：**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"mcp-grafana\",\n \"args\": [\n \"--tls-cert-file\",\n \"\u002Fpath\u002Fto\u002Fclient.crt\",\n \"--tls-key-file\",\n \"\u002Fpath\u002Fto\u002Fclient.key\",\n \"--tls-ca-file\",\n \"\u002Fpath\u002Fto\u002Fca.crt\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"https:\u002F\u002Fsecure-grafana.example.com\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003C您的服务账户令牌>\"\n }\n }\n }\n}\n```\n\n**Docker 示例：**\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-v\",\n \"\u002Fpath\u002Fto\u002Fcerts:\u002Fcerts:ro\",\n \"-e\",\n \"GRAFANA_URL\",\n \"-e\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\",\n \"grafana\u002Fmcp-grafana\",\n \"-t\",\n \"stdio\",\n \"--tls-cert-file\",\n \"\u002Fcerts\u002Fclient.crt\",\n \"--tls-key-file\",\n \"\u002Fcerts\u002Fclient.key\",\n \"--tls-ca-file\",\n \"\u002Fcerts\u002Fca.crt\"\n ],\n \"env\": {\n \"GRAFANA_URL\": \"https:\u002F\u002Fsecure-grafana.example.com\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003C您的服务账户令牌>\"\n }\n }\n }\n}\n```\n\nTLS 配置会应用于 MCP 服务器使用的所有 HTTP 客户端，包括：\n\n- 主 Grafana OpenAPI 客户端\n- Prometheus 数据源客户端\n- Loki 数据源客户端\n- 事件管理客户端\n- Sift 调查客户端\n- 告警客户端\n- Asserts 客户端\n\n**直接 CLI 使用示例：**\n\n对于使用自签名证书进行测试：\n\n```bash\n.\u002Fmcp-grafana --tls-skip-verify -debug\n```\n\n使用客户端证书身份验证：\n\n```bash\n.\u002Fmcp-grafana \\\n --tls-cert-file \u002Fpath\u002Fto\u002Fclient.crt \\\n --tls-key-file \u002Fpath\u002Fto\u002Fclient.key \\\n --tls-ca-file \u002Fpath\u002Fto\u002Fca.crt \\\n -debug\n```\n\n仅使用自定义 CA 证书：\n\n```bash\n.\u002Fmcp-grafana --tls-ca-file \u002Fpath\u002Fto\u002Fca.crt\n```\n\n**程序化使用：**\n\n如果您以编程方式使用此库，也可以创建支持 TLS 的上下文函数：\n\n```go\n\u002F\u002F 使用结构体字面量\ntlsConfig := &mcpgrafana.TLSConfig{\n CertFile: \"\u002Fpath\u002Fto\u002Fclient.crt\",\n KeyFile: \"\u002Fpath\u002Fto\u002Fclient.key\",\n CAFile: \"\u002Fpath\u002Fto\u002Fca.crt\",\n}\ngrafanaConfig := mcpgrafana.GrafanaConfig{\n Debug: true,\n TLSConfig: tlsConfig,\n}\ncontextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)\n\n\u002F\u002F 或者内联\ngrafanaConfig := mcpgrafana.GrafanaConfig{\n Debug: true,\n TLSConfig: &mcpgrafana.TLSConfig{\n CertFile: \"\u002Fpath\u002Fto\u002Fclient.crt\",\n KeyFile: \"\u002Fpath\u002Fto\u002Fclient.key\",\n CAFile: \"\u002Fpath\u002Fto\u002Fca.crt\",\n },\n}\ncontextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)\n```\n\n### 服务器 TLS 配置（仅限可流式传输的 HTTP 传输）\n\n当使用可流式传输的 HTTP 传输（`-t streamable-http`）时，您可以配置 MCP 服务器以提供 HTTPS 而不是 HTTP。这在需要保护 MCP 客户端与服务器之间连接的安全性时非常有用。\n\n服务器支持以下 TLS 配置选项，用于可流式传输的 HTTP 传输：\n\n- `--server.tls-cert-file`：用于服务器 HTTPS 的 TLS 证书文件路径（启用 TLS 所需）\n- `--server.tls-key-file`：用于服务器 HTTPS 的 TLS 私钥文件路径（启用 TLS 所需）\n\n**注意**：这些标志与上述文档中描述的客户端 TLS 标志完全分开。客户端 TLS 标志配置的是 MCP 服务器如何连接到 Grafana，而这些服务器 TLS 标志则配置的是客户端在使用可流式传输的 HTTP 传输时如何连接到 MCP 服务器。\n\n**使用 HTTPS 可流式传输 HTTP 服务器的示例：**\n\n```bash\n.\u002Fmcp-grafana \\\n -t streamable-http \\\n --server.tls-cert-file \u002Fpath\u002Fto\u002Fserver.crt \\\n --server.tls-key-file \u002Fpath\u002Fto\u002Fserver.key \\\n -addr :8443\n```\n\n这将在 HTTPS 端口 8443 上启动 MCP 服务器。客户端将连接到 `https:\u002F\u002Flocalhost:8443\u002F`，而不是 `http:\u002F\u002Flocalhost:8000\u002F`。\n\n**带有服务器 TLS 的 Docker 示例：**\n\n```bash\ndocker run --rm -p 8443:8443 \\\n -v \u002Fpath\u002Fto\u002Fcerts:\u002Fcerts:ro \\\n -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 \\\n -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003C您的服务账户令牌> \\\n grafana\u002Fmcp-grafana \\\n -t streamable-http \\\n -addr :8443 \\\n --server.tls-cert-file \u002Fcerts\u002Fserver.crt \\\n --server.tls-key-file \u002Fcerts\u002Fserver.key\n```\n\n### 健康检查端点\n\n当使用 SSE（`-t sse`）或可流式传输的 HTTP（`-t streamable-http`）传输时，MCP 服务器会在 `\u002Fhealthz` 上暴露一个健康检查端点。负载均衡器、监控系统或编排平台可以使用此端点来验证服务器是否正在运行并接受连接。\n\n**端点：** `GET \u002Fhealthz`\n\n**响应：**\n- 状态码：`200 OK`\n- 正文：`ok`\n\n**使用示例：**\n\n```bash\n# 对于默认端口上的可流式传输 HTTP 或 SSE 传输\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealthz\n\n# 使用自定义地址\ncurl http:\u002F\u002Flocalhost:9090\u002Fhealthz\n```\n\n**注意：** 健康检查端点仅在使用 SSE 或可流式传输的 HTTP 传输时可用。当使用 stdio 传输（`-t stdio`）时，它不可用，因为 stdio 不会暴露 HTTP 服务器。\n\n### 可观测性\n\nMCP 服务器支持 Prometheus 指标和 OpenTelemetry 分布式追踪，遵循 [OTel MCP 语义约定](https:\u002F\u002Fopentelemetry.io\u002Fdocs\u002Fspecs\u002Fsemconv\u002Fgen-ai\u002Fmcp\u002F)。\n\n#### 指标\n\n当使用 SSE 或可流式 HTTP 传输时，可通过 `--metrics` 标志启用 Prometheus 指标：\n\n```bash\n# 在主服务器的 \u002Fmetrics 路径上提供指标\n.\u002Fmcp-grafana -t streamable-http --metrics\n\n# 在独立地址上提供指标\n.\u002Fmcp-grafana -t streamable-http --metrics --metrics-address :9090\n```\n\n**可用指标：**\n\n| 指标 | 类型 | 描述 |\n|--------|------|-------------|\n| `mcp_server_operation_duration_seconds` | 直方图 | MCP 操作持续时间（标签：`mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`） |\n| `mcp_server_session_duration_seconds` | 直方图 | MCP 客户端会话持续时间（标签：`network_transport`, `mcp_protocol_version`） |\n| `http_server_request_duration_seconds` | 直方图 | HTTP 服务器请求持续时间（来自 otelhttp） |\n\n**注意：** 指标仅在使用 SSE 或可流式 HTTP 传输时可用。它们在使用 stdio 传输时不可用。\n\n#### 追踪\n\n分布式追踪通过标准的 `OTEL_*` 环境变量进行配置，并且与 `--metrics` 标志无关。当设置了 `OTEL_EXPORTER_OTLP_ENDPOINT` 时，服务器会通过 OTLP\u002FgRPC 导出追踪数据：\n\n```bash\n# 将追踪数据发送到本地 Tempo 实例\nOTEL_EXPORTER_OTLP_ENDPOINT=http:\u002F\u002Flocalhost:4317 \\\nOTEL_EXPORTER_OTLP_INSECURE=true \\\n.\u002Fmcp-grafana -t streamable-http\n\n# 将追踪数据发送到 Grafana Cloud 并进行身份验证\nOTEL_EXPORTER_OTLP_ENDPOINT=https:\u002F\u002Ftempo-us-central1.grafana.net:443 \\\nOTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Basic ...\" \\\n.\u002Fmcp-grafana -t streamable-http\n```\n\n工具调用跨度遵循 semconv 命名规范（`tools\u002Fcall \u003Ctool_name>`），并包含诸如 `gen_ai.tool.name`, `mcp.method.name` 和 `mcp.session.id` 等属性。服务器还支持从工具调用请求的 `_meta` 字段中传播 W3C 追踪上下文。\n\n**带有指标和追踪功能的 Docker 示例：**\n\n```bash\ndocker run --rm -p 8000:8000 \\\n -e GRAFANA_URL=http:\u002F\u002Flocalhost:3000 \\\n -e GRAFANA_SERVICE_ACCOUNT_TOKEN=\u003Cyour token> \\\n -e OTEL_EXPORTER_OTLP_ENDPOINT=http:\u002F\u002Ftempo:4317 \\\n -e OTEL_EXPORTER_OTLP_INSECURE=true \\\n grafana\u002Fmcp-grafana \\\n -t streamable-http --metrics\n```\n\n## 故障排除\n\n### Grafana 版本兼容性\n\n如果您在使用与数据源相关的工具时遇到以下错误：\n\n```\nget datasource by uid : [GET \u002Fdatasources\u002Fuid\u002F{uid}][400] getDataSourceByUidBadRequest {\"message\":\"id is invalid\"}\n```\n\n这通常表明您使用的 Grafana 版本早于 9.0。`\u002Fdatasources\u002Fuid\u002F{uid}` API 端点是在 Grafana 9.0 中引入的，在较早版本上执行数据源操作将会失败。\n\n**解决方案：** 将您的 Grafana 实例升级到 9.0 或更高版本以解决此问题。\n\n## 开发\n\n欢迎贡献！如果您有任何建议或改进，请随时提交问题或拉取请求。\n\n该项目使用 Go 编写。请按照适用于您平台的说明安装 Go。\n\n要在本地以 STDIO 模式运行服务器（这是本地开发的默认模式），请使用：\n\n```bash\nmake run\n```\n\n要在本地以 SSE 模式运行服务器，请使用：\n\n```bash\ngo run .\u002Fcmd\u002Fmcp-grafana --transport sse\n```\n\n您还可以使用自定义构建的 Docker 镜像以 SSE 传输方式运行服务器。与发布的 Docker 镜像一样，该自定义镜像的入口点默认为 SSE 模式。要构建镜像，请使用：\n\n```\nmake build-image\n```\n\n然后以 SSE 模式（默认）运行镜像：\n\n```\ndocker run -it --rm -p 8000:8000 mcp-grafana:latest\n```\n\n如果您需要改为以 STDIO 模式运行，则可以覆盖传输设置：\n\n```\ndocker run -it --rm mcp-grafana:latest -t stdio\n```\n\n### 测试\n\n有三种类型的测试可供使用：\n\n1. 单元测试（无需外部依赖）：\n\n```bash\nmake test-unit\n```\n\n您也可以通过以下命令运行单元测试：\n\n```bash\nmake test\n```\n\n2. 集成测试（需要运行中的 Docker 容器）：\n\n```bash\nmake test-integration\n```\n\n3. 云测试（需要云端 Grafana 实例和凭据）：\n\n```bash\nmake test-cloud\n```\n\n> 注意：云测试会在 CI 中自动配置。对于本地开发，您需要自行设置 Grafana Cloud 实例和凭据。\n\n更全面的集成测试需要在本地 3000 端口上运行一个 Grafana 实例；您可以使用 Docker Compose 启动它：\n\n```bash\ndocker-compose up -d\n```\n\n集成测试可以通过以下命令运行：\n\n```bash\nmake test-all\n```\n\n如果您正在添加更多工具，请为它们添加集成测试。现有的测试应该是一个很好的起点。\n\n### 代码检查\n\n要对代码进行检查，请运行：\n\n```bash\nmake lint\n```\n\n这包括一个自定义 linter，用于检查 `jsonschema` 结构体标签中未转义的逗号。`description` 字段中的逗号必须用 `\\\\,` 转义，以防止静默截断。您也可以单独运行此 linter：\n\n```bash\nmake lint-jsonschema\n```\n\n有关详细信息，请参阅 [JSONSchema Linter 文档](internal\u002Flinter\u002Fjsonschema\u002FREADME.md)。\n\n## 许可证\n\n本项目采用 [Apache License, Version 2.0](LICENSE) 许可。\n\n[mcp]: https:\u002F\u002Fmodelcontextprotocol.io\u002F\n[service-account]: https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Fadministration\u002Fservice-accounts\u002F#add-a-token-to-a-service-account-in-grafana","# mcp-grafana 快速上手指南\n\n`mcp-grafana` 是一个基于模型上下文协议（MCP）的 Grafana 服务器，允许 AI 客户端（如 Claude Desktop、Cursor）直接访问和操作你的 Grafana 实例及其生态系统。\n\n## 环境准备\n\n在开始之前，请确保满足以下要求：\n\n1. **Grafana 实例**：\n * 需要 **Grafana 9.0** 或更高版本以获得完整功能支持。\n * 早期版本可能因缺少 API 端点而导致部分数据源相关操作失败。\n2. **前置依赖**：\n * 安装 **[uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F)** 包管理器。\n3. **服务账户令牌**：\n * 在 Grafana 中创建一个服务账户（Service Account），并生成一个具有相应权限的令牌（Token）。\n * *注意*：根据你计划使用的功能（如查询 Prometheus、管理告警等），需为该服务账户配置相应的 RBAC 权限。\n\n## 安装步骤\n\n本工具主要通过 `uvx` 运行，无需单独安装二进制文件。你需要在 MCP 客户端的配置文件中添加服务器配置。\n\n以 **Claude Desktop** 或 **Cursor** 为例，编辑其 MCP 配置文件（通常为 `claude_desktop_config.json` 或类似位置），添加以下内容：\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-grafana\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\n**配置说明：**\n* `GRAFANA_URL`: 替换为你的 Grafana 实例地址。如果是 Grafana Cloud，请使用类似 `https:\u002F\u002Fmyinstance.grafana.net` 的地址。\n* `GRAFANA_SERVICE_ACCOUNT_TOKEN`: 替换为你刚才生成的服务账户令牌。\n\n## 基本使用\n\n配置完成后，重启你的 MCP 客户端（如 Claude Desktop 或 Cursor）。AI 助手将自动连接至 `mcp-grafana` 服务器，你可以直接通过自然语言指令进行操作。\n\n### 常用场景示例\n\n1. **查找仪表盘**\n > “帮我搜索标题中包含‘系统监控’的仪表盘。”\n\n2. **获取仪表盘摘要**\n > “获取 UID 为 `abc-123` 的仪表盘摘要，我想了解它包含哪些面板类型。”\n > *提示：使用摘要功能比获取完整 JSON 更节省上下文窗口。*\n\n3. **执行 PromQL 查询**\n > “查询 Prometheus 数据源中 `node_cpu_seconds_total` 指标在过去 1 小时的平均值。”\n > *注意：运行面板查询工具默认禁用，如需启用需在启动参数中添加 `--enabled-tools runpanelquery`。*\n\n4. **生成深层链接**\n > “为我生成指向 UID 为 `xyz-789` 仪表盘中第 5 号面板的直接链接，时间范围设为最近 1 小时。”\n\n### 高级配置（可选）\n\n如果你希望禁用某些不常用的功能以节省资源或提高安全性，可以在 `args` 中添加禁用标志。例如，禁用 OnCall 和导航链接生成功能：\n\n```json\n{\n \"mcpServers\": {\n \"grafana\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-grafana\", \"--disable-oncall\", \"--disable-navigation\"],\n \"env\": {\n \"GRAFANA_URL\": \"http:\u002F\u002Flocalhost:3000\",\n \"GRAFANA_SERVICE_ACCOUNT_TOKEN\": \"\u003Cyour service account token>\"\n }\n }\n }\n}\n```\n\n其他可选启用的工具组包括：`runpanelquery`（运行面板查询）、`examples`（查询示例）、`clickhouse`、`cloudwatch`、`searchlogs`、`elasticsearch` 和 `admin`。请根据实际需求在 `args` 中使用 `--enabled-tools` 或 `--disable-\u003Ccategory>` 进行配置。","某电商平台的 SRE 工程师在深夜收到核心交易接口响应延迟告警，需要迅速定位是数据库瓶颈还是应用层问题，并临时调整监控视图以聚焦关键指标。\n\n### 没有 mcp-grafana 时\n- **手动检索低效**：工程师需登录 Grafana Web 界面，在数十个仪表盘中手动搜索“交易核心”相关看板，反复切换页面确认 UID，耗时且容易出错。\n- **上下文割裂**：为了查看某个面板的具体 PromQL 查询语句或数据源配置，必须点击进入编辑模式复制 JSON，再粘贴到本地分析，打断排查思路。\n- **修改门槛高**：若需在现有看板中新增一个针对特定错误码的监控面板，需导出完整 JSON 文件，在本地编辑器中小心修改结构后再导入，极易因格式错误导致看板崩溃。\n- **信息过载**：直接获取完整看板 JSON 会消耗大量注意力及 AI 助手的上下文窗口，导致后续分析其他日志时出现记忆丢失或截断。\n\n### 使用 mcp-grafana 后\n- **智能精准定位**：通过自然语言指令，mcp-grafana 直接搜索并返回相关看板摘要（Summary），快速锁定目标 UID，无需人工逐页翻阅。\n- **无缝获取细节**：利用 JSONPath 功能，仅提取特定面板的查询语句和数据源类型，既保留了关键排查信息，又极大节省了上下文空间。\n- **敏捷动态调整**：直接使用 Patch 功能对看板进行微调，如临时添加一个过滤特定错误码的面板，无需处理庞大的完整 JSON 文件，操作安全且高效。\n- **即时数据验证**：启用 Run Panel Query 功能，直接在对话中执行查询并获取实时数据结果，快速验证假设，缩短从“怀疑”到“确认”的路径。\n\n核心价值在于将 Grafana 从被动的可视化展示平台转变为可交互的智能运维助手，显著降低故障排查的认知负荷与操作成本。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fgrafana_mcp-grafana_29d0ee28.png","grafana","Grafana Labs","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fgrafana_4017b0e9.jpg","Grafana Labs is behind leading open source projects Grafana and Loki, and the creator of the first open & composable observability platform.",null,"hello@grafana.com","https:\u002F\u002Fgrafana.com","https:\u002F\u002Fgithub.com\u002Fgrafana",[85,89,93,97,101,105],{"name":86,"color":87,"percentage":88},"Go","#00ADD8",93.6,{"name":90,"color":91,"percentage":92},"Python","#3572A5",5.3,{"name":94,"color":95,"percentage":96},"JavaScript","#f1e05a",0.6,{"name":98,"color":99,"percentage":100},"Makefile","#427819",0.3,{"name":102,"color":103,"percentage":104},"Dockerfile","#384d54",0.1,{"name":106,"color":107,"percentage":108},"Shell","#89e051",0,2698,319,"2026-04-02T21:16:44","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":116,"python":117,"dependencies":118},"1. 需要 Grafana 9.0 或更高版本。2. 推荐使用 uv 工具运行 (uvx mcp-grafana)。3. 需配置环境变量 GRAFANA_URL 和 GRAFANA_SERVICE_ACCOUNT_TOKEN。4. 部分功能（如 Run Panel Query, ClickHouse, CloudWatch, Search Logs, Elasticsearch, Admin）默认禁用，需通过 --enabled-tools 标志启用。5. 若使用面板渲染功能，需安装并配置 Grafana Image Renderer 服务。6. 创建服务账户时需根据使用的工具分配相应的 RBAC 权限。","未说明 (通过 uv\u002Fuvx 运行，通常隐含 Python 环境，但 README 未指定具体版本)",[119,67],"uv",[13,15],"2026-03-27T02:49:30.150509","2026-04-06T08:46:24.289813",[124,129,134,139,144,149],{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},11527,"为什么使用 streamable-http 传输协议时会报错 \"Invalid transport type\"？","请确保在配置传输类型时使用连字符 `streamable-http`，而不是下划线 `streamable_http`。错误信息明确指出有效的类型必须是 'stdio'、'sse' 或 'streamable-http'。","https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F177",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},11528,"调用 listPrometheusLabelNames 工具时出现格式错误或服务器错误，原因是什么？","这通常是由于 Grafana 版本过低导致的。mcp-grafana 使用数据源 UID 来调用 API，这需要较新版本的 Grafana（如 v12.0+）支持通过 UID 进行数据源代理调用。如果你使用的是旧版本（如 v8.5+），它仅支持通过数据源 ID 调用，从而导致错误。建议升级 Grafana 版本。此外，检查 `matches` 参数的格式，通常不需要额外的方括号 `[]`。","https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F197",{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},11529,"为什么 prometheus_query 工具返回空数组，而在 Grafana Explore 中查询却有结果？","这通常是因为查询缺少明确的时间戳。如果 LLM 代理没有提供当前时间或显式设置时间范围，查询可能会失败或返回空结果。建议在调用工具时显式传递时间戳参数，或者确保代理能够访问当前时间。未来版本可能会支持如 `now` 或 `now-1h` 这样的相对时间表达式。","https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F121",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},11530,"在 SSE 模式下启动 MCP 服务器后无法连接或收到 404 错误，如何解决？","请确保你使用的是 v0.2.1 或更高版本，该版本修复了 SSE 传输的相关问题。另外注意，在早期版本中，SSE 传输可能未正确使用 `GRAFANA_URL` 环境变量，请升级至最新修复版本以解决此问题。","https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F40",{"id":145,"question_zh":146,"answer_zh":147,"source_url":148},11531,"调用 list_prometheus_metric_names 或 list_prometheus_metric_metadata 时出现 JSON 解组错误怎么办？","错误信息 `json: cannot unmarshal string into Go struct field ... of type int` 表明参数类型不匹配。请检查传入的 `limit` 参数，确保它是整数类型（int），而不是字符串类型。","https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F63",{"id":150,"question_zh":151,"answer_zh":152,"source_url":153},11532,"Tempo MCP 服务器是否已可用？","是的，Tempo MCP 服务器的支持已经合并到主分支中，现在可以使用相关工具进行 Trace 搜索和分析。","https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fissues\u002F53",[155,160,165,170,175,180,185,190,195,200,205,210,215,220,225,230,235,240,245,250],{"id":156,"version":157,"summary_zh":158,"released_at":159},62043,"v0.11.4","### 新增功能\n\n- Pyroscope 系列查询及性能剖析数据探索的统一查询工具 ([#672](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F672))\n- 用于与 Grafana 应用平台资源交互的通用 Kubernetes 风格 API 客户端 ([#690](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F690))\n- `--session-idle-timeout-minutes` CLI 标志，用于自动关闭空闲会话 ([#691](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F691))\n- 接受 `X-Grafana-Service-Account-Token` 头作为替代身份验证方法 ([#280](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F280))\n- 对 `alerting_manage_rules` 列表操作进行服务器端过滤，以减少响应大小 ([#629](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F629))\n- 支持来自 Loki ≥ 3.0 的分类标签，以实现更好的标签发现 ([#671](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F671))\n- Gemini CLI 扩展配置，用于设置 Grafana URL、令牌和组织 ID ([#665](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F665))\n- 自动从 Grafana 前端设置中获取公共 URL，以生成更准确的深度链接 ([#664](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F664))\n- 支持针对 Google Cloud Monitoring 数据源的 PromQL 查询 ([#647](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F647))\n- 为 `query_loki_logs` 提供查询元数据和可配置的结果限制 ([#654](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F654))\n\n### 修复问题\n\n- 创建\u002F更新告警规则工具中缺失的参数现已正确暴露 ([#663](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F663))\n- 处理来自 Grafana API 的 `text\u002F*` 内容类型响应，而非在非 JSON 响应时失败 ([#694](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F694))\n- 在流式 HTTP 模式下通过正确清理资源来防止内存泄漏 ([#685](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F685))\n- 在 `\u002Fresources` 和 `\u002Fproxy` 数据源端点之间进行回退，以提高数据源兼容性 ([#562](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F562))\n- 当缺少组织 ID 时发出警告，而不是静默丢弃该参数 ([#678](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F678))\n- 支持 `get_panel_image` 中的多值仪表板变量 ([#677](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F677))\n- 在仪表板补丁操作中返回针对不支持的 JSONPath 语法的可操作错误 ([#675](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F675))\n- 将 Prometheus POST 请求转换为 GET，以兼容不支持 POST 的数据源 ([#633](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F633))\n- 修复了 `explore` 资源类型的 `generate_deeplink` 功能 ([#644](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F644))\n- 防止导致某些 LLM 提供商出错的裸布尔 JSON Schema 值 ([#597](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F597))\n- 防止 `get_dashboard_panel_queries` 中的空指针崩溃 ([#661](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F661))\n\n### 变更内容\n\n- 使用灵活的 inte","2026-04-02T07:53:13",{"id":161,"version":162,"summary_zh":163,"released_at":164},62044,"v0.11.3","### 新增\n\n- 在 `get_dashboard_panel_queries` 中支持面板过滤和模板变量替换，以便更精准地提取查询语句 ([#539](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F539))\n- 新增 `alerting_manage_routing` 工具，用于在一个统一的工具中管理通知策略、联系人点和时间间隔 ([#618](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F618))\n- 为 CloudWatch 工具添加 `accountId` 参数，以支持跨账户监控 ([#616](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F616))\n\n### 修复\n\n- 将 `OrgIDRoundTripper` 添加到 Grafana 客户端传输链中，确保所有请求都能正确发送组织 ID ([#649](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F649))\n\n### 变更\n\n- 将告警规则相关工具整合为一个 `alerting_manage_rules` 工具，以简化发现流程 ([#619](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F619))\n- 使用类型化的结构体来表示告警查询参数，而非使用无类型的 `models.AlertQuery` ([#630](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F630))\n- 为告警客户端添加服务器端过滤支持，以提高规则查询效率（Grafana 10.0+）([#612](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F612))\n\n\n","2026-03-12T21:25:13",{"id":166,"version":167,"summary_zh":168,"released_at":169},62045,"v0.11.2","### 变更\n\n- 使用 Go 交叉编译优化 Docker 构建，以加快多平台镜像的构建速度 ([#600](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F600))\n- 修复 Python wheel 子包的构建，使其使用正确的 `--package-path` 标志 ([#601](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F601))\n\n\n","2026-02-25T09:11:41",{"id":171,"version":172,"summary_zh":173,"released_at":174},62046,"v0.11.1","### 新增\n\n- 新增 `run_panel_query` 工具，可直接执行仪表板面板查询，支持 Prometheus、Loki、ClickHouse 和 CloudWatch 数据源，以及模板变量替换、Grafana 宏展开和批量多面板查询功能（[#542](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F542)）\n\n### 变更\n\n- 合并近似重复的 MCP 工具，以减少工具总数，从而便于大语言模型选择合适的工具（[#596](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F596)）","2026-02-24T13:41:57",{"id":176,"version":177,"summary_zh":178,"released_at":179},62047,"v0.11.0","### 新增\n\n- 支持 Elasticsearch 数据源，提供 Lucene 和 Query DSL 语法、时间范围过滤以及可配置的结果限制（[#424](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F424)）\n- 支持 CloudWatch 数据源，提供命名空间、指标和维度的发现工具，以及引导式查询工作流（[#536](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F536)）\n\n### 修复\n\n- 支持标准 HTTP 代理环境变量（`HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY`），以便通过企业代理进行连接（[#578](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F578)）","2026-02-19T12:15:39",{"id":181,"version":182,"summary_zh":183,"released_at":184},62048,"v0.10.0","### 新增功能\n\n- ClickHouse 数据源支持（[#535](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F535)）\n- `get_query_examples` 工具，用于从数据源获取查询示例（[#538](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F538)）\n- `query_prometheus_histogram` 工具，用于直方图百分位数查询，并自动生成 PromQL 的 `histogram_quantile` 函数（[#537](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F537)）\n- `list_datasources` 和 `search_dashboards` 工具支持分页，可配置 limit 和 offset 参数（[#543](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F543)）\n- 通过 `GRAFANA_EXTRA_HEADERS` 环境变量支持自定义 HTTP 头，适用于自定义认证方案和反向代理集成（[#522](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F522)）\n- Prometheus 指标和 OpenTelemetry 集成（[#506](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F506)）\n- 基于 Alpine 的 Docker 镜像变体（`:alpine` 和 `:x.y.z-alpine` 标签），镜像体积更小（约 74MB 对比 147MB）（[#568](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F568)）\n- 支持按索引对仪表板数组元素执行 `remove` 操作（[#564](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F564)）\n\n### 修复\n\n- 改进了 `update_dashboard` 工具的描述和错误信息，以减少大语言模型的误用（[#570](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F570)）\n- 移除了仪表板补丁操作路径中的多余空格（[#565](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F565)）\n- 为端到端测试引入 DeepEval MCP 评估（[#516](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F516)）\n\n### 安全性\n\n- 升级 Docker 基础镜像中的软件包，以修复 OpenSSL 的严重漏洞 CVE-2025-15467（CVSS 9.8）（[#551](https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F551)）","2026-02-12T16:12:55",{"id":186,"version":187,"summary_zh":188,"released_at":189},62049,"v0.9.0","## 更改日志\n* 671c7a23bb29f8c5d5199dab5560ce2251f96b17 修复 Prometheus 数据源代理 URL，使其使用资源端点 (#483)\n* c5fb3090a14cf5ea8e6c4d8175cd6119ce2131a2 杂项(依赖): 将 \u002Ftests 中的 pyasn1 从 0.6.1 升级到 0.6.2 (#495)\n* ead16b21060c57ce7e9134fb998b819338129281 杂项(依赖): 更新 golang:1.24-bookworm Docker 摘要至 1c64c58 (#486)\n* 4cb32dd134c4a4f1972f8082c075f49d5025a6a6 杂项(依赖): 更新 grafana\u002Fshared-workflows\u002F 动作至 (#474)\n* 599e2ac547eacc830ef62c48398fdc5d59f034f8 杂项(依赖): 更新 grafana\u002Fshared-workflows\u002F 动作至 (#490)\n* 7009f18fd60334ea4b383c4946223ba65d05d571 杂项(依赖): 更新 sd2k\u002Fmcp-tokens-action 摘要至 54ab17c (#500)\n* cd790d7f43785c9e0e2a69e4b85671bfa2f32232 杂项(开发依赖): 在 \u002Ftests 中将 mcp 从 1.12.4 升级到 1.23.0 (#514)\n* 9c3817e5f2086f1e189b25478ceb4a3b99fe2ec9 杂项: 始终对令牌检查添加注释 (#480)\n* 975e081c5d9dd9f4f0b8fa1d9264c4950d9dd183 杂项: 在 server.json 中提升 schema 版本 (#482)\n* e6e0e661ef04de72c6b4b85c7dfe8e5e168b0722 功能: 添加 Loki 模式 query_loki_patterns 工具 (#499)\n* c22b5f6d0b067dd08927de0a15091f3b121e037f 修复(loki): 支持带有正确标签解析的指标查询 (#510)\n* ec7c906e1e9b94ed2b92fc480e8e23b6d7169170 修复(测试): 更新 Claude 模型，从 langevals 切换到 deepeval (#373)\n* 3c42e137d30db185d167b12258314572adddc87d 修复: 集中处理工具错误 (#505)\n\n\n---\n由 [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser) 发布。","2026-01-28T14:15:59",{"id":191,"version":192,"summary_zh":193,"released_at":194},62050,"v0.8.2","## 更改日志\n* f31ee69c8164a949f2c1992d920e9f59e38e956d 杂项：在最终阶段使用 bookworm (#479)\n\n\n---\n由 [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser) 发布。\n","2026-01-14T18:06:41",{"id":196,"version":197,"summary_zh":198,"released_at":199},62051,"v0.8.1","## 更改日志\n* 8e07aac1c97385bfbfc1a4154090075de1abb8d6 杂项：将构建 Docker 镜像的基础镜像从 bullseye 升级到 bookworm (#475)\n* c6f5ea0846f3f174122a272d431eb48fe9f1a5b2 CI：在每次提交时构建 Docker 镜像，仅在打标签时推送 (#476)\n\n\n---\n由 [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser) 发布。\n","2026-01-14T14:54:51",{"id":201,"version":202,"summary_zh":203,"released_at":204},62052,"v0.8.0","## 更改日志\n* 07a85ccd7de0e7ec1881552b4cb898376708b003 杂项(ci): 添加使用 sd2k\u002Fmcp-token 的令牌比较 CI 作业 (#416)\n* 03ef87691d6c593d924b86d9508e82991a668232 杂项(deps): 升级 actions\u002Fsetup-go (#469)\n* 64fdbcb3bce63f8b29f479bd490d983cbcb8b3c3 杂项(deps): 升级 dawidd6\u002Faction-download-artifact (#453)\n* 3167706c2b9f74938578274a6815b00273944e5c 杂项(deps): 升级 github.com\u002Fprometheus\u002Fcommon (#452)\n* 6e0850cc7109e130b1aea11559e5119ff188fca2 杂项(deps): 升级 github.com\u002Fprometheus\u002Fprometheus (#463)\n* a34ca3a8056bbf81638a34e307cba6e3bb55ab75 杂项(deps): 在一个目录中对 github-actions 组进行 7 次更新 (#420)\n* a602423d723a8c92d9b65582824d258a3fc12f23 杂项(deps): 对 github-actions 组进行 2 次更新 (#464)\n* 40f38596a7b7fc94f255af7d3015dcf87ba45d98 杂项(deps): 在一个目录中对 go-dependencies 组进行 7 次更新 (#413)\n* 6d1d4f61969958e82b1d315164caa687255cd0ec 杂项(deps): 对 go-dependencies 组进行 2 次更新 (#419)\n* 420c63a21534922f93555569b1ffca422fd238c3 杂项(deps): 将 actions\u002Fcheckout 动作更新至 v5.0.1 (#434)\n* 61d44a5c0703823f403ac15183c884de119e511f 杂项(deps): 将 actions\u002Fcheckout 动作更新至 v6 (#438)\n* 777919ca40d8ce3d3e67dbe8ac1a0dfb0156cc2f 杂项(deps): 更新 actions\u002Fcheckout 的摘要 (#392)\n* 26dde3053c7354aa21a0216f14eecf2d07864fe0 杂项(deps): 将 actions\u002Fcheckout 的摘要更新为 0c366fd (#470)\n* 0fae3310825244b8237e276efdc7b86f4e7145f8 杂项(deps): 将 dawidd6\u002Faction-download-artifact 的摘要更新为 9e12ab9 (#449)\n* a5d5e1538a716bac25ba7e9fd96944c3765cb0bd 杂项(deps): 将 debian:bullseye-slim docker 的摘要更新为 5fc1d68 (#393)\n* 772b9748c899df61b745b3f639e7003a2111d00a 杂项(deps): 将 debian:bullseye-slim docker 的摘要更新为 b32674f (#471)\n* 8c926fabb154d262d0eb68dca9039478139c210e 杂项(deps): 将 debian:bullseye-slim docker 的摘要更新为 c5f48c9 (#450)\n* fb3b423cfbbff81c884aa3009348ba992e6a862a 杂项(deps): 将 grafana\u002Fgrafana docker 的摘要更新为 2175aaa (#443)\n* c1ecc83847592414f2de0d032bbb49b98717d252 杂项(deps): 将 grafana\u002Fgrafana docker 的摘要更新为 adaf2d6 (#402)\n* a24efea848f8e82d97e052da4fce62d550688401 杂项(deps): 将 grafana\u002Floki docker 的标签更新为 v3 (#367)\n* f48433b013a18ac518922210e8e19a4bb8a1832f 杂项(deps): 将 grafana\u002Floki docker 的标签更新为 v3.6.3 (#451)\n* c60ee4e303fe36bd1ee2a6051f8d7973a64a1b2a 杂项(deps): 将 grafana\u002Fpromtail docker 的标签更新为 v2.9.17 (#435)\n* 73961a964225b5501c42017a710d8a4a37552770 杂项(deps): 将 grafana\u002Fpromtail docker 的标签更新为 v3 (#440)\n* fe8bb28e93755d6335c412e6384b68f01d019273 杂项(deps): 将 grafana\u002Fpyroscope docker 的标签更新为 v1.16.0 (#436)\n* b4bff301b8095dc5db822f704aa46212771865b8 杂项(deps): 将 grafana\u002Fpyroscope docker 的标签更新为 v1.17.0 (#454)\n* ed654d0e52e8abb10dc6696659382ad7af4fc34b 杂项(deps): 将 grafana\u002Fshared-workflows\u002F 动作更新至 (#421)\n* b2c6a61757f09a37bedf4059eb6239fa54c8f4e3 杂项(deps): 将 grafana\u002Fshared-workflows\u002F 动作更新至 (#425)\n* 5020d0f2ec164c35dc9e453ebb5dade0fc596fb9 杂项(deps): 将 grafana\u002Fshared","2026-01-14T13:37:15",{"id":206,"version":207,"summary_zh":208,"released_at":209},62053,"v0.7.10","## Changelog\n* a893328f0d78c52286d9abab8825aa901ad0f409 chore(deps): update grafana\u002Fshared-workflows\u002F action to (#394)\n* 5ff432c30928e5cf93d419f194be73058e3a83c3 feat: add support for datasource-managed alerts (#362)\n* b05b370800fe460c4388ed54a3360a8918c3f992 fix: include default values in jsonschema (#399)\n* ed4a600af50a4cbbbdb976d7fe7425f40a81ad43 forward X-Grafana-OrgID for proxies mcps (#407)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-12-03T09:01:21",{"id":211,"version":212,"summary_zh":213,"released_at":214},62054,"v0.7.9","## Changelog\n* 48a597950ca1ad10244126fa8249a58c56344e34 Add --disable-write flag to control write operations (#385)\n* 22ae2eaf7b11ec95bf8305e140a2164e24439ffa add renovate json (#370)\n* 935d308c1f658c92212531f05b607238b39f365c chore(deps): bump the github-actions group across 1 directory with 4 updates (#386)\n* 8f1bbdcaf31349cdfa2f19bc31c3cf62f8dc1907 chore(deps): bump the github-actions group with 2 updates (#359)\n* 922788291bc51554ee7b0f88ba288d9a4273a38c chore(deps): bump the go-dependencies group across 1 directory with 6 updates (#387)\n* 688a94cba1347d80d75888104372f26cd608be83 chore(deps): bump the go-dependencies group with 3 updates (#358)\n* f8c639adff6f3a507838345f4d2f36531dede8fc chore(deps): update dependency mcp to v1.10.0 [security] (#352)\n* 75fded98e9fba0eb684617e9ff9b14df8a62b9e4 chore(deps): update grafana\u002Fgrafana docker digest to 35c41e0 (#353)\n* 65bc858bb257430cb7d2832b3f732b4bd011cf0a chore(deps): update grafana\u002Floki docker tag to v2.9.15 (#349)\n* d7ebde09951351009b57f340035139272b7977a6 chore(deps): update grafana\u002Fpromtail docker tag to v2.9.15 (#350)\n* 28da7ba07e62d80f2e4972fa83ea6f85c00605da chore(deps): update grafana\u002Fpyroscope docker tag to v1.15.0 (#364)\n* 17a1107d9d6e69b134d93010bf3f54caafc2b547 chore(deps): update grafana\u002Fshared-workflows\u002F action to (#346)\n* d8ca62185565f69a4585d5e918f617db033eaa72 chore(deps): update grafana\u002Fshared-workflows\u002F action to (#356)\n* 4b0939de376f132d287b354c22555590a9c7be99 chore(deps): update grafana\u002Fshared-workflows\u002F action to (#365)\n* 2612eb35ff54d48f684943f085faf7d519696c53 chore(deps): update grafana\u002Fshared-workflows\u002Fget-vault-secrets action to v1.3.0 (#366)\n* e6b52c5f4ddc97bcdf783e84ed657f06ab1f201a chore(deps): update hoverkraft-tech\u002Fcompose-action digest to 2c655a3 (#371)\n* a43aab0f63f42ddc93a1f8046eefa82a60a1c348 chore(deps): update prom\u002Fprometheus docker digest to 4921475 (#363)\n* 019dba6822773c39711e2de8e6018e9a281c11ad chore: add Claude Code plugin configuration (#333)\n* 67f6a910ba484caaf5a4bfe780258fbc33c5f6d4 chore: use new schema version for MCP registry server (#351)\n* 0dcc16cabe5acb923c0ba46cdba60985fc215638 ci(docker): add multi-platform build support (#369)\n* 903f1fff8e0adabd5acd097b0baf461e8fd848f0 feat: add annotation tools with unit tests and docs updates (#312) (#374)\n* 5b281813c7719b94d2bf83db4fcd1d64bb121c4c fix: generate correct JSON schemas for empty structs (#396)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-11-14T13:34:44",{"id":216,"version":217,"summary_zh":218,"released_at":219},62055,"v0.7.8","## Changelog\n* 8bec2db659cc2ee433095e0aac3a170d8d527956 chore(deps): bump github.com\u002Fprometheus\u002Fprometheus (#343)\n* 68f33c1423ca4accdf5e0175881842dce892389b chore(deps): bump the github-actions group with 2 updates (#344)\n* 5539c61d92cc51d67f984dde3458887680318833 chore(deps): pin dependencies (#337)\n* adc0fd1d18ec7abd3304acfe4378c096ad631678 chore(deps): update actions\u002Fcheckout digest to ff7abcd (#338)\n* 22188baa581c4bc8e705e4190440d033e5af6834 chore(deps): update goreleaser\u002Fgoreleaser-action digest to a08664b (#339)\n* 7103b9d0e3c4607dbc10f69df4e46f80d7a40690 chore(deps): update grafana\u002Fshared-workflows\u002F action to (#340)\n* 4507428f30ca361e64dbfa6d3ea8b4c6b40d2903 chore(deps): update hoverkraft-tech\u002Fcompose-action digest to ccd64b0 (#341)\n* 013b86998656775d720e8ce3e6ce9e6762910971 feat: add support for org id header (#336)\n* 3a32dd00de820761e88f8c9034a7480a4661250b feat: add support for proxying to Tempo datasources' MCP servers (#314)\n* 73451db2473d58eb539b5ef245b94c3140122189 fix: add org ID param to cloud testing util function (#345)\n* e7371495bf83e8af8cae6dc3c391d6d9b3c14835 fix: specify prerelease_suffix for goreleaser git config (#332)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-21T09:38:59",{"id":221,"version":222,"summary_zh":223,"released_at":224},62056,"v0.7.7-rc.3","## Changelog\n* 51d3d65674bc792bebdd7acb4dd6569cf6ced818 chore: don't push 'latest' tag if it's rc\u002Fdev etc (#329)\n* b05b8a0589fe5f95c3f8caee1b6d44f822972641 fix: correctly pipe filters in jq invocation (#330)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-15T12:59:24",{"id":226,"version":227,"summary_zh":228,"released_at":229},62057,"v0.7.7-rc.2","## Changelog\n* 0e312bfc098940b2b7ff88770852916bad377166 fix: use correct label in Docker image (#328)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-15T12:31:45",{"id":231,"version":232,"summary_zh":233,"released_at":234},62058,"v0.7.7-rc.1","## Changelog\n* c23dfac206bea109b9f0596d6f8b4aba0fa22a07 fix: add version to package identifier and version field (#327)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-15T12:22:28",{"id":236,"version":237,"summary_zh":238,"released_at":239},62059,"v0.7.6","## Changelog\n* 82003f4b50f1243e4ced3cae7905ec738a68bb30 fix version (#326)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-15T08:57:40",{"id":241,"version":242,"summary_zh":243,"released_at":244},62060,"v0.7.5","## Changelog\n* 0e246a9ffacdb75e8c50328e032266420c6baa79 fix: don't use registryBaseUrl in server.json (#325)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-15T08:29:05",{"id":246,"version":247,"summary_zh":248,"released_at":249},62061,"v0.7.4","## Changelog\n* 2c3bde3977f4bd2357505c17e0530e36469b342f chore(deps): bump github.com\u002Fprometheus\u002Fcommon (#317)\n* 192b26e7b1327cc147b41fdcc97a587489e853b2 chore(deps): bump the github-actions group across 1 directory with 3 updates (#321)\n* 43bc281fe4f6ad29cd6cf2ee60f7e1797eaaa7e9 chore: add server.json for MCP registry (#323)\n* aca244bb4d09ffcc51ea31780685b559c6f18f66 chore: strip 'v' prefix off Docker image tag (#319)\n* 3c57f7710065d8acf0a313c4887b6bcd62a21c04 feat: add health check endpoint on \u002Fhealthz (#322)\n* 48e982b811eed1d649543f138ba0e5369186728e fix: update connectrpc\u002Fconnect-go to resolve the compile error (#316)\n* 5ed6922b19e95df849c25cd653305668a23be62f fix: use separate step to extract image tag (#324)\n\n\n---\nReleased by [GoReleaser](https:\u002F\u002Fgithub.com\u002Fgoreleaser\u002Fgoreleaser).\n","2025-10-15T07:10:48",{"id":251,"version":252,"summary_zh":253,"released_at":254},62062,"v0.7.3","## What's Changed\r\n* [MINOR]Add tools to create and search folders by @failedanswer in https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F303\r\n* chore(deps): bump the go-dependencies group with 4 updates by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F304\r\n* chore(deps): bump the go-dependencies group with 2 updates by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F311\r\n* chore(deps): bump the github-actions group with 2 updates by @dependabot[bot] in https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F310\r\n* feat: add more alerting tools by @sd2k in https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F292\r\n* Build and push image to docker hub by @ioanarm in https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fpull\u002F313\r\n\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fgrafana\u002Fmcp-grafana\u002Fcompare\u002Fv0.7.2...v0.7.3","2025-10-10T14:01:04"]