@pooml/mcp

pooml용 MCP 서버: 로그와 메트릭을 Claude 또는 다른 MCP 클라이언트에서 일반 SQL로 조회할 수 있습니다.

사용자 머신에서 실행되고(stdio), pooml 인스턴스와 읽기 전용 query API를 통해 통신합니다. 자격 증명은 로컬에 유지되며, pooml 서버에는 MCP 관련 설정이 필요하지 않습니다.

도구

• query_logs - 로그에 대한 SQL (레벨, 서비스, FTS5를 통한 전체 텍스트 검색)

• query_metrics - 메트릭에 대한 SQL (카운터와 게이지)

• list_metrics - 존재하는 메트릭을 나열하여 모델이 이름을 추측하지 않도록 함

엄격한 읽기 전용: 모든 쿼리는 pooml의 계층적 SQL 검증을 거칩니다 (SELECT 전용, 허용 목록의 테이블, 읽기 전용 연결, 시간 초과, 행 수 제한).

설정

1. pooml 서버에서 query API를 활성화합니다: POOML_QUERY_API_ENABLED=true 및 POOML_QUERY_AUTH_SECRET=<min 32 chars>.

2. MCP 클라이언트에 추가합니다. Claude Code의 경우:

claude mcp add pooml \
  -e POOML_URL=https://your-pooml-host:8080 \
  -e POOML_QUERY_AUTH_SECRET=your-query-secret \
  -- npx -y @pooml/mcp

또는 .mcp.json에:

{
  "mcpServers": {
    "pooml": {
      "command": "npx",
      "args": ["-y", "@pooml/mcp"],
      "env": {
        "POOML_URL": "https://your-pooml-host:8080",
        "POOML_QUERY_AUTH_SECRET": "your-query-secret"
      }
    }
  }
}

pooml이 Access를 사용하는 Cloudflare Tunnel 뒤에 있는 경우 서비스 토큰을 추가하세요: POOML_CF_ACCESS_CLIENT_ID 및 POOML_CF_ACCESS_CLIENT_SECRET.

왜 SQL인가

pooml의 핵심은 관찰 가능성 데이터가 SQL로 쿼리되는 SQLite라는 점이며, LLM은 이미 SQL을 유창하게 구사합니다. 모델이 환각을 일으킬 수 있는 사용자 지정 쿼리 언어는 없습니다: SELECT service, COUNT(*) FROM logs WHERE level >= 4 ...라고 작성하면 답을 얻을 수 있습니다.

라이선스

Apache-2.0