{"_id":"grafana-mcp","_rev":"4-068e130546092d200f7bb496b394b755","name":"grafana-mcp","dist-tags":{"latest":"0.1.3"},"versions":{"0.1.0":{"name":"grafana-mcp","version":"0.1.0","keywords":["mcp","mcp-server","modelcontextprotocol","grafana","loki","prometheus","tempo","observability","logging","ai","agent","bun"],"author":{"url":"https://itzhouq.cn","name":"itzhouq","email":"zhouq218@gmail.com"},"license":"MIT","_id":"grafana-mcp@0.1.0","maintainers":[{"name":"itzhouq","email":"itzhouq@163.com"}],"homepage":"https://itzhouq.cn","bugs":{"url":"https://github.com/itzhouq/grafana-mcp/issues"},"bin":{"grafana-mcp":"index.ts"},"dist":{"shasum":"e3467a15ecd4ca41192a8e382be992e0f2283da1","tarball":"https://registry.npmjs.org/grafana-mcp/-/grafana-mcp-0.1.0.tgz","fileCount":8,"integrity":"sha512-Zjo/AF9CWWo4VspDH5AYcVTxiU7uCmOJlfnIN6tqu0fMyXfNu+rHEmIYdv6BLIhaUeHpQGdhedwyMSb+uozfgA==","signatures":[{"sig":"MEUCIE22cBZuVN6d7vAX4MpHUFU3QF+EBGjDz/7z3/0I/FYvAiEAiUp+xYLmSyL8BV6+VUt8lEwg95gvblq0zsjlPG4whw4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":58697},"type":"module","engines":{"bun":">=1.0.0"},"gitHead":"e00203a7d9fdb134063de16b5addd680be35a9c8","scripts":{"test":"bun run test/smoke.ts && bun run test/integration.ts","smoke":"bun run test/smoke.ts","start":"bun run index.ts"},"_npmUser":{"name":"itzhouq","email":"itzhouq@163.com"},"repository":{"url":"git+https://github.com/itzhouq/grafana-mcp.git","type":"git"},"_npmVersion":"10.9.4","description":"Project-level read-only Grafana MCP server: Loki/Prometheus/Tempo/Alerts with test-prod switching and per-project context. Zero deps, runs on bun.","directories":{},"_nodeVersion":"22.22.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/grafana-mcp_0.1.0_1791384266559_0.09470811524567457","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"grafana-mcp","version":"0.1.1","keywords":["mcp","mcp-server","modelcontextprotocol","grafana","loki","prometheus","tempo","observability","logging","ai","agent","bun"],"author":{"url":"https://itzhouq.cn","name":"itzhouq","email":"zhouq218@gmail.com"},"license":"MIT","_id":"grafana-mcp@0.1.1","maintainers":[{"name":"itzhouq","email":"itzhouq@163.com"}],"homepage":"https://itzhouq.cn","bugs":{"url":"https://github.com/itzhouq/grafana-mcp/issues"},"bin":{"grafana-mcp":"index.ts"},"dist":{"shasum":"d75aa6b312e8501ac04bd348dd3f5e3467a6c295","tarball":"https://registry.npmjs.org/grafana-mcp/-/grafana-mcp-0.1.1.tgz","fileCount":8,"integrity":"sha512-WJRsgmJ42qF2BcJQWNsKely35M5OlH9ElLIbFLrv5BlYmIkLAoQs3Hm3MbMBGj61U3URy44doO7yADhttzQ6Aw==","signatures":[{"sig":"MEYCIQDmnZJEHvfvHl2qGuqnkhGpbXCfkcPTgyS0iHY4bKR5MQIhAP/skqlZAXBtgjMJT9ghjfgPCTB7C0+Bj/7X/4wqluFY","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIAfSZmAAdx55KY1BbY6a2uNUsuDLbJIfeUcz/ixLMvCFAiBmcZQ1/w9RPEqHyVx/2LKlRwZRZ9eFnEkXTHG2cEUAFA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":58866},"type":"module","engines":{"bun":">=1.0.0"},"gitHead":"e81575e67e12161a4361dbc3de07fc8bbcf79225","mcpName":"io.github.itzhouq/grafana-mcp","scripts":{"test":"bun run test/smoke.ts && bun run test/integration.ts","smoke":"bun run test/smoke.ts","start":"bun run index.ts"},"_npmUser":{"name":"itzhouq","email":"itzhouq@163.com"},"repository":{"url":"git+https://github.com/itzhouq/grafana-mcp.git","type":"git"},"_npmVersion":"10.9.4","description":"Project-level read-only Grafana MCP server: Loki/Prometheus/Tempo/Alerts with test-prod switching and per-project context. Zero deps, runs on bun.","directories":{},"_nodeVersion":"22.22.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/grafana-mcp_0.1.1_1791384523416_0.8143957856054138","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"grafana-mcp","version":"0.1.2","keywords":["mcp","mcp-server","modelcontextprotocol","grafana","loki","prometheus","tempo","observability","logging","ai","agent","bun"],"author":{"url":"https://itzhouq.cn","name":"itzhouq","email":"zhouq218@gmail.com"},"license":"MIT","_id":"grafana-mcp@0.1.2","maintainers":[{"name":"itzhouq","email":"itzhouq@163.com"}],"homepage":"https://itzhouq.cn","bugs":{"url":"https://github.com/itzhouq/grafana-mcp/issues"},"bin":{"grafana-mcp":"index.ts"},"dist":{"shasum":"1904b7013d34fcb19a8cd4923c1a43ac70f80dac","tarball":"https://registry.npmjs.org/grafana-mcp/-/grafana-mcp-0.1.2.tgz","fileCount":8,"integrity":"sha512-0mrjWelfvl1X7i/34wC2K+wiXNB/miJlpdYVw2E28XpXmpWEug8MvHjnL3pFVKqKHpXVOjyEbojTfvTeed5SbQ==","signatures":[{"sig":"MEQCIG/GT11oDEtWR719Qw2Cv3VEsy4/WrolNXss8dDvx4WgAiBuCkvoele0TR2KIM/JBTo8+JhtoqJOJDZ6w2mvdtPyyg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIERUNU1ttlhgPErl1YAeCbS5sZfheLUAgBGxJGaAE3mCAiEAmoJUq4PivhaXcvEjlyCcVPwU0e2SGzZY4Cj8dFeRekw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59244},"type":"module","engines":{"bun":">=1.0.0"},"gitHead":"0098fb228add0e27618720df097af39c8cdce85c","mcpName":"io.github.itzhouq/grafana-mcp","scripts":{"test":"bun run test/smoke.ts && bun run test/integration.ts","smoke":"bun run test/smoke.ts","start":"bun run index.ts"},"_npmUser":{"name":"itzhouq","email":"itzhouq@163.com"},"repository":{"url":"git+https://github.com/itzhouq/grafana-mcp.git","type":"git"},"_npmVersion":"10.9.4","description":"Project-level read-only Grafana MCP server: Loki/Prometheus/Tempo/Alerts with test-prod switching and per-project context. Zero deps, runs on bun.","directories":{},"_nodeVersion":"22.22.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/grafana-mcp_0.1.2_1791385181583_0.2537244873663982","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"_id":"grafana-mcp@0.1.3","bin":{"grafana-mcp":"index.ts"},"bugs":{"url":"https://github.com/itzhouq/grafana-mcp/issues"},"dist":{"shasum":"7138b28f32cb50b8dfb026a086ae21a155bbce4e","tarball":"https://registry.npmjs.org/grafana-mcp/-/grafana-mcp-0.1.3.tgz","fileCount":8,"integrity":"sha512-8wZwnSEOh3/AfU9ISoCyYLu2/SMIcwYdjYMRkvwHA35rz3VoCv9I21Kbq5xOde+UxO1aiIVwOIRvlk/ZvCvzcA==","signatures":[{"sig":"MEYCIQDX40j7z3wjLtRfOisu3p+uXQv0xh3r2OtWijLhJTP9VQIhAPrdD+IFXU48B7r5WSIQKtwLgaksmqSm5Tz28AzJKWXB","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH1UpzMjlXxwpXodWUGKyTWcUAt+xWfWsgdiVqEje9jJAiA/quLENX7nHRgwLoHFY9VYu9c1oJ/dtdATM3JU4GRIKw=="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/grafana-mcp@0.1.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":59367},"name":"grafana-mcp","type":"module","author":{"url":"https://itzhouq.cn","name":"itzhouq","email":"zhouq218@gmail.com"},"engines":{"bun":">=1.0.0"},"gitHead":"0fb0787b74a8908b79f5129d56b32bb9dd6d20ce","license":"MIT","mcpName":"io.github.itzhouq/grafana-mcp","scripts":{"test":"bun run test/smoke.ts && bun run test/integration.ts","smoke":"bun run test/smoke.ts","start":"bun run index.ts"},"version":"0.1.3","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"587690f8-65af-4dcd-8fd7-24109df01ece"}},"homepage":"https://itzhouq.cn","keywords":["mcp","mcp-server","modelcontextprotocol","grafana","loki","prometheus","tempo","observability","logging","ai","agent","bun"],"repository":{"url":"git+https://github.com/itzhouq/grafana-mcp.git","type":"git"},"_npmVersion":"12.2.0","description":"Project-level read-only Grafana MCP server: Loki/Prometheus/Tempo/Alerts with test-prod switching and per-project context. Zero deps, runs on bun.","directories":{},"maintainers":[{"name":"itzhouq","email":"itzhouq@163.com"}],"_nodeVersion":"22.23.3","_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/grafana-mcp_0.1.3_1791388935868_0.36375842194961905"}}},"time":{"created":"2026-10-07T14:44:26.438Z","modified":"2026-10-07T16:02:18.471Z","0.1.0":"2026-10-07T14:44:26.703Z","0.1.1":"2026-10-07T14:48:43.505Z","0.1.2":"2026-10-07T14:59:41.683Z","0.1.3":"2026-10-07T16:02:15.970Z"},"bugs":{"url":"https://github.com/itzhouq/grafana-mcp/issues"},"author":{"url":"https://itzhouq.cn","name":"itzhouq","email":"zhouq218@gmail.com"},"license":"MIT","homepage":"https://itzhouq.cn","keywords":["mcp","mcp-server","modelcontextprotocol","grafana","loki","prometheus","tempo","observability","logging","ai","agent","bun"],"repository":{"url":"git+https://github.com/itzhouq/grafana-mcp.git","type":"git"},"description":"Project-level read-only Grafana MCP server: Loki/Prometheus/Tempo/Alerts with test-prod switching and per-project context. Zero deps, runs on bun.","maintainers":[{"name":"itzhouq","email":"itzhouq@163.com"}],"readme":"# grafana-mcp\n\n[![CI](https://github.com/itzhouq/grafana-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/itzhouq/grafana-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/grafana-mcp)](https://www.npmjs.com/package/grafana-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Built with Bun](https://img.shields.io/badge/runtime-bun-f472b6)](https://bun.sh)\n\n**Project-level Grafana MCP server** — give your AI coding agent read-only access to Loki logs, Prometheus metrics, Tempo traces and alerts, with per-project context and test/prod environment switching. 零依赖单文件 TypeScript，bun 直接运行。\n\n```text\nAI 编码 Agent（Claude Code / Cursor / …）\n        │  MCP (stdio)\n        ▼\n   grafana-mcp ──读──▶ ~/.zshrc / ~/.zshenv / 项目 .grafana.json（凭据与项目上下文）\n        │  HTTP（只读查询 API）\n        ▼\n   Grafana ──▶ Loki（日志）/ Prometheus（指标）/ Tempo（链路）/ Alerts（告警）\n```\n\n## 它解决什么问题\n\n日常迭代业务系统时，测试阶段要快速定位 QA 反馈的问题，线上要快速排查功能 bug 与性能瓶颈——这些证据都在 Grafana 体系里（Loki 日志、Prometheus 指标、Tempo 链路）。让 agent 在写代码、修 bug 的同时能直接查到这些上下文，问题定位的效率和准确性会明显提升。但直接用通用 MCP 封装 Grafana API 会遇到三个实际障碍：\n\n| 痛点 | 本实现的解法 |\n|---|---|\n| 每个项目会话都要口头告诉 agent \"我们的应用在 Grafana 里叫什么\"，容易跑偏 | 项目根放一个 `.grafana.json`（app、namespace、默认环境），agent 调 `project_context` 一次对齐方向 |\n| test / prod 双环境凭据区分，而 MCP server 由客户端 spawn，是非交互 shell，**不会 source `.zshrc`**，环境变量读不到 | server 启动时直接**解析 `~/.zshrc` / `~/.zshenv` 文件文本**提取 `GRAFANA_{ENV}_*` 变量，完全不依赖 shell 环境 |\n| 多数据源实例上\"按类型取第一个\"容易选错 | 优先使用显式配置的数据源 UID，支持按环境指定 |\n\n## 声明\n\n1. **非官方项目**：本仓库与 Grafana Labs 无隶属关系；Grafana、Loki、Prometheus、Tempo 是各自所有方的商标。\n2. **免责**：软件按\"现状\"提供。使用者需自行确保对目标 Grafana 实例的访问已获授权，并遵守所在组织的数据安全与审计规定；日志与指标输出可能包含业务敏感信息，分享查询结果前请自行判断合规边界。作者不对违规使用及其后果负责。\n3. **只读边界**：全部 10 个工具均为查询类，不含任何写操作。建议为 agent 配置 **Viewer 角色的专用账号**（最小权限），不要复用管理员凭据。\n\n## 快速开始\n\n前提：本机已安装 [bun](https://bun.sh)（`curl -fsSL https://bun.sh/install | bash`）。项目零 npm 依赖，无需 `npm install`。\n\n### 1. 在项目的 `.mcp.json` 中接入\n\n```json\n{\n  \"mcpServers\": {\n    \"grafana\": {\n      \"command\": \"bunx\",\n      \"args\": [\"grafana-mcp\"],\n      \"env\": {\n        \"GRAFANA_ENV\": \"test\",\n        \"GRAFANA_APP\": \"my-app\"\n      }\n    }\n  }\n}\n```\n\n- `GRAFANA_ENV`：该项目默认环境（省略则默认 `test`，安全兜底）\n- `GRAFANA_APP`：该应用在 Grafana/Loki 中的 app 标签值（也可以放到 `.grafana.json`，见下）\n- 重启会话后生效；Claude Code 也可用 `claude mcp add` 交互添加\n\n偏好克隆使用的话：\n\n```bash\ngit clone https://github.com/itzhouq/grafana-mcp.git && cd grafana-mcp\nbun run index.ts          # stdio JSON-RPC，接入任意 MCP 客户端\n```\n\n`.mcp.json` 中对应写 `\"command\": \"bun\", \"args\": [\"run\", \"/path/to/grafana-mcp/index.ts\"]`。\n\n### 2.（推荐）在项目根创建 `.grafana.json`\n\n比 `.mcp.json` env 能承载更多信息，且对 agent 可见可解释：\n\n```json\n{\n  \"defaultEnv\": \"test\",\n  \"app\": \"my-app\",\n  \"appLabel\": \"app\",\n  \"namespace\": \"my-namespace\",\n  \"notes\": \"本项目日志标签 app=my-app；查指标时 pod 前缀为 my-app-\"\n}\n```\n\n| 字段 | 说明 |\n|---|---|\n| `defaultEnv` | 默认环境（`test` / `prod` / 自定义） |\n| `app` | 应用在 Loki 中的 app 标签值，`loki_query` 会自动注入到查询 selector |\n| `appLabel` | app 标签名，默认 `app` |\n| `namespace` | 默认 namespace，供 agent 参考 |\n| `notes` | 自由文本备注，`project_context` 会原样带给 agent |\n| `environments.{env}.datasources` | 按环境指定数据源 UID（不配则按数据源类型自动发现） |\n\n> ⚠️ `.grafana.json` 的 `notes` 是自由文本，可能包含内部信息——建议把它加进项目的 `.gitignore`。\n\n## 环境配置从哪来\n\n无需任何操作：server 启动时读取 `~/.zshenv` 和 `~/.zshrc` **文件内容**（而非 shell 环境），解析其中的：\n\n```shell\nexport GRAFANA_TEST_URL=...        export GRAFANA_PROD_URL=...\nexport GRAFANA_TEST_USER=...       export GRAFANA_PROD_USER=...\nexport GRAFANA_TEST_PASSWORD=...   export GRAFANA_PROD_PASSWORD=...\nexport GRAFANA_TEST_LOKI_DATASOURCE=...      export GRAFANA_PROD_LOKI_DATASOURCE=...\nexport GRAFANA_TEST_PROMETHEUS_DATASOURCE=... export GRAFANA_PROD_PROMETHEUS_DATASOURCE=...\nexport GRAFANA_DEFAULT_ENV=test   # 可选：全局默认环境\n```\n\n修改 `.zshrc` 后重启会话即生效。环境切换用 `switch_environment` 工具，或 `.mcp.json` 里 `GRAFANA_ENV` 指定默认值。\n\n字段级优先级（从低到高，逐字段合并）：\n\n```\n~/.zshenv + ~/.zshrc 文本解析\n  → 全局配置 ~/.config/grafana-mcp/config.json（可选，适合无 .zshrc 的机器）\n    → 项目 .grafana.json\n      → 进程环境变量（.mcp.json env：GRAFANA_URL/USER/PASSWORD 直连，或 GRAFANA_{ENV}_URL 按环境覆盖）\n```\n\n## 工具列表\n\n| 工具 | 说明 |\n|---|---|\n| `project_context` | **调查前必调**：激活环境、可用环境、项目 App/namespace、数据源 UID、配置来源（密码脱敏输出） |\n| `switch_environment` | 切换 test/prod（仅影响当前会话），返回新环境上下文 |\n| `loki_query` | LogQL 日志查询；项目配置了 app 时自动注入 selector（`injectApp=false` 可关） |\n| `loki_labels` | 列 Loki 标签名，或查某标签全部取值（如确认 app 名称在当前环境是否存在） |\n| `prom_query` | PromQL 区间查询 |\n| `prom_instant` | PromQL 即时查询 |\n| `tempo_search` | TraceQL 链路搜索 |\n| `tempo_trace` | 按 traceID 查看完整链路 |\n| `alerts` | 当前正在告警的规则 |\n| `datasources` | 列出全部数据源 |\n\n时间参数（loki/prom/tempo 通用）：`range`（默认 `1h`，如 `30m`/`6h`/`24h`）、`start`/`end`（ISO 8601 绝对时间）、`limit`。\n\n## 与官方 mcp-grafana 的差异\n\n[Grafana 官方](https://github.com/grafana/mcp-grafana)也提供 MCP server（Go 实现，面向全局单实例的完整工具集）。两者定位不同，可并存：\n\n| | grafana-mcp（本仓库） | 官方 mcp-grafana |\n|---|---|---|\n| 使用粒度 | **项目级**：项目根 `.grafana.json` 声明上下文，`project_context` 一次对齐 | 全局实例，项目信息需每次口头提供 |\n| 多环境 | **test/prod 双环境**一等公民，`switch_environment` 一键切换 | 面向单一实例配置 |\n| 凭据来源 | 解析 `~/.zshrc`/`~/.zshenv` 文本（适配 MCP 客户端非交互 shell）+ 环境变量 + 配置文件 | 环境变量 |\n| 形态 | 零依赖单文件 TypeScript，bun 直接运行 | Go 二进制 / Docker |\n\n选型建议：要全量 Grafana 管理能力用官方；要\"每个业务项目开箱即用的日志/指标排查上下文 + 双环境\"，用本仓库。\n\n## 安全提示\n\n- Grafana 账号建议使用 **Viewer 角色**的专用账号，不要复用管理员凭据。\n- 凭据明文存于 `~/.zshrc`（或进程环境），MCP server 仅在本机内存中使用，不落盘、不回显（`project_context` 输出对密码脱敏）。\n- 如需集中管理，可把连接信息放到 `~/.config/grafana-mcp/config.json` 并 `chmod 600`，`~/.zshrc` 中的同名变量会被其覆盖。\n- 支持 1Password 回退（可选）：设置 `GRAFANA_OP_VAULT` / `GRAFANA_OP_ITEM` 后，无账密时通过 `op` CLI 取凭据。\n\n## FAQ\n\n**为什么 agent 读不到 `.zshrc` 里的环境变量？**\nMCP server 由客户端 spawn，是非交互、非登录 shell，不会 source rc 文件。本实现因此直接解析 rc 文件文本，这是特性而非 workaround。\n\n**不想装 bun？**\n当前运行时依赖 bun（单文件 TS 直跑是刻意的设计取舍）。Node 兼容的编译产物在 Roadmap 中，欢迎 issue 催更。\n\n**查询结果太长被截断？**\n超过 6 万字符自动截断并提示缩小范围；命中 limit 上限时也会明确提示可能还有更多。建议总是带 `range` 与 `limit`。\n\n**数据源选错了？**\n在 `GRAFANA_{ENV}_LOKI_DATASOURCE` 等变量或 `.grafana.json` 的 `environments.{env}.datasources` 中显式指定 UID。\n\n## 本地开发\n\n```bash\nbun run smoke    # MCP 协议握手 + 工具清单 + project_context；本机配好凭据后自动追加真实查询\nbun run test     # 冒烟 + 集成测试（项目上下文发现、app 注入、prod 切换；需要真实凭据，CI 跳过）\n```\n\nCI 只运行无凭据的协议级冒烟测试与敏感信息扫描；集成测试需要真实 Grafana 环境，请在本机运行。\n\n## Roadmap\n\n- [ ] Node 兼容编译产物（降低 bun 前提）\n- [ ] 仪表盘面板数据读取\n- [ ] 更多环境变量发现来源（direnv 等）\n\n## 关于作者\n\nitzhouq — 个人网站 [itzhouq.cn](https://itzhouq.cn)，在那里持续 build in public。其他开源工具：\n\n- [archery-mcp](https://github.com/itzhouq/archery-mcp) — 让 AI 只读接入 Archery SQL 审计平台的 MCP server（生产表结构查询 + 上线 SQL 预检）\n\n欢迎 issue / PR；安全漏洞请走 [SECURITY.md](SECURITY.md) 的私密渠道，不要开 public issue。\n\n---\n\nmcp-name: io.github.itzhouq/grafana-mcp\n","readmeFilename":"README.md"}