grafana-log-mcp

grafana-log-mcp는 Grafana/Loki를 위한 범용적이고 재사용 가능한 로그 조회 계층으로, 읽기 전용 stdio MCP 서버로 제공됩니다. Grafana API와 통신하여 원시 로그와 집계 뷰(느린 로그, 오류 지문, 볼륨 추세)를 반환하며, 시간 창, 프로젝트, 키워드 또는 소요 시간 임계값으로 필터링합니다.

의도적으로 비즈니스 특화 로직이나 휴리스틱을 포함하지 않습니다. 로그를 확보한 후 이를 소스 코드와 연관 짓고 왜 그런 일이 발생했는지 설명하는 것은 디버깅 중인 비즈니스 프로젝트의 AI IDE와 skills/rules에 맡겨집니다. 서버는 단지 데이터를 제공할 뿐입니다.

중국어 설명: 이는 범용 로그 조회 계층입니다(데이터 조회, 집계, 로그 반환만 수행하며 비즈니스 전반에 재사용 가능). 비즈니스 분석이나 근본 원인 규명은 내장되어 있지 않습니다. 구체적인 원인 분석은 호출 측 AI가 비즈니스 프로젝트 소스 코드와 프로젝트 자체의 skill/경험을 결합하여 수행합니다.

설치

# 方式一：npm 全局安装（推荐）
npm install -g grafana-log-mcp

전역 설치 후 두 가지 명령이 제공됩니다: grafana-log-mcp(MCP Server 시작), grafana-log-mcp-login(대화형 로그인).

설치하지 않고 npx로 일회성 실행도 가능합니다: npx -y grafana-log-mcp / npx -y grafana-log-mcp-login.

Related MCP server: grafana-mcp

빠른 시작

npm 설치됨(소비자)

# 1. 登录（交互输入 Grafana 地址与用户名密码，写入 ~/.grafana-log-mcp/credentials.json，0600）
grafana-log-mcp-login

# 2. 校验凭证（排查"MCP 突然查不了"）
grafana-log-mcp-login --check

# 3. 启动 MCP Server（stdio）
grafana-log-mcp

소스 개발(리포지토리 clone 후)

# 1. 安装依赖（node >= 18）
npm install

# 2. 登录
node bin/login.js

# 3. 校验凭证
node bin/login.js --check

# 4. 启动 MCP Server（stdio）
npm start          # 即 node src/index.js

AI IDE 연동(Trae/Claude 등)

MCP 구성에 추가합니다(각 IDE의 구성 형식에 따라):

{
  "mcpServers": {
    "grafana-log": {
      "command": "npx",
      "args": ["-y", "grafana-log-mcp"],
      "env": { "GRAFANA_URL": "https://your-grafana.example.com" }
    }
  }
}

전역 활성화 권장: 문제 해결 시 비즈니스 프로젝트 소스 리포지토리를 열게 되므로, MCP 구성을 전역으로 추가하면 어떤 리포지토리에서든 바로 "질문 → 로그 조회 → 코드 읽기 → 원인 제시"가 가능합니다.

도구(15개)

데이터 양에 대한 세 가지 하드 상한: limit ≤ 1000, 한 줄 500자, 응답 25k자(초과 시 앞뒤를 유지하고 중간을 생략하며 표시). 한 줄이 잘린 경우 get_full_line으로 해당 줄의 time 기준 전체 내용을 가져올 수 있습니다.

프로젝트 등록(projects.json)

등록 파일은 다음 우선순위로 위치가 결정됩니다(list_projects가 반환하는 summary.configFile에 현재 실제 적용 위치가 표시됩니다):

1. GRAFANA_CONFIG_PATH 환경 변수로 지정된 파일

2. 패키지 내 config/projects.json(소스 리포지토리 내)

3. ~/.grafana-log-mcp/projects.json(자격 증명과 같은 디렉터리, npm 설치 후 기본 위치)

참고 형식은 config/projects.example.json에 있으며, 각 항목은 key / datasourceUid / labels{app,group} / aliases(中文别名) / repoPath를 포함합니다. repoPath는 AI IDE가 코드를 찾는 용도로만 사용되며, MCP 자체는 소스 코드를 읽지 않습니다. 장애 지식 베이스는 config/failure-patterns.json에 있으며, 새로운 장애 유형을 만나면 항목을 추가하면 됩니다.

환경 변수(선택 사항)

GRAFANA_URL=                  # Grafana 地址：作为 grafana-log-mcp-login 的默认地址，并覆盖凭证文件中的地址
GRAFANA_ORG_ID=1              # 可选：仅影响 build_explore_url 生成的 Explore 深链的 orgId 参数（默认 1）；不参与实际日志查询
GRAFANA_CREDENTIALS_PATH=     # 自定义凭证文件位置
GRAFANA_CONFIG_PATH=          # 自定义项目登记文件（projects.json）位置
GRAFANA_MOCK=1                # 本地 mock 模式：不连真实 Grafana、无需登录（2500 条合成日志，验证翻页/截断/慢日志）

설명: MCP는 Grafana 기본 주소와 프로젝트 구성을 내장하지 않습니다(범용화). 주소는 로그인 시 입력(자격 증명 파일) 또는 GRAFANA_URL 환경 변수에서 가져옵니다. 인스턴스 관련 구성(프로젝트 등록, 데이터 소스 uid)은 projects.json에서 유지 관리합니다(위 섹션의 위치 결정 규칙 참조).

테스트

node test/unit.mjs         # 纯逻辑单测（合成日志，无网络依赖）：59 通过
node test/integration.mjs  # 编排器端到端（mock client + 独立 fixture 配置）：20 通过