elastic-apm-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,65 @@
+# elastic-apm-mcp-server
+
+Kibana APM API를 통해 서비스 목록, 트랜잭션 성능, 에러를 조회하는 MCP 서버입니다.
+
+## 요구사항
+
+- Node.js 18 이상
+- Kibana 8.x (내부 APM API를 사용하므로 버전에 따라 동작이 달라질 수 있습니다)
+
+## 설정
+
+Claude Desktop 또는 Claude Code 설정에 다음을 추가합니다. 별도 설치 없이 `npx`로 바로 실행됩니다.
+
+### Claude Code
+
+`~/.claude/settings.json` 또는 프로젝트의 `.claude/settings.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "elastic-apm": {
+      "command": "npx",
+      "args": ["-y", "elastic-apm-mcp-server"],
+      "env": {
+        "KIBANA_URL": "http://your-kibana-host:5601",
+        "KIBANA_USERNAME": "your-username",
+        "KIBANA_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 에 동일한 형식으로 추가합니다.
+
+### 환경변수
+
+| 환경변수 | 필수 | 설명 |
+|----------|------|------|
+| `KIBANA_URL` | O | Kibana 접속 URL |
+| `KIBANA_USERNAME` | O | Kibana 사용자 이름 |
+| `KIBANA_PASSWORD` | O | Kibana 비밀번호 |
+
+## 제공 도구
+
+| 도구 | 설명 |
+|------|------|
+| `list_services` | APM에 등록된 서비스 목록 조회 |
+| `get_service_overview` | 특정 서비스의 트랜잭션 성능과 에러 요약 조회 |
+| `get_transactions` | 특정 서비스의 트랜잭션 성능 통계 조회 |
+| `get_errors` | 특정 서비스의 에러 그룹 조회 |
+
+## 사용 예시
+
+MCP 설정 후 Claude에게 자연어로 요청하면 됩니다.
+
+- "APM 서비스 목록 보여줘"
+- "auth-service의 최근 1시간 에러 조회해줘"
+- "payment-service 트랜잭션 성능 확인해줘"
+
+## License
+
+ISC

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { KibanaClient } from "./kibana-client.js";
+import { registerServiceTools } from "./tools/services.js";
+import { registerErrorTools } from "./tools/errors.js";
+import { registerTransactionTools } from "./tools/transactions.js";
+const kibanaUrl = process.env.KIBANA_URL;
+const username = process.env.KIBANA_USERNAME;
+const password = process.env.KIBANA_PASSWORD;
+if (!kibanaUrl || !username || !password) {
+    console.error("KIBANA_URL, KIBANA_USERNAME, KIBANA_PASSWORD environment variables are required");
+    process.exit(1);
+}
+const client = new KibanaClient(kibanaUrl, username, password);
+const server = new McpServer({
+    name: "elastic-apm-mcp-server",
+    version: "1.0.0",
+});
+registerServiceTools(server, client);
+registerErrorTools(server, client);
+registerTransactionTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/kibana-client.js

@@ -0,0 +1,89 @@
+export class KibanaClient {
+    baseUrl;
+    headers;
+    constructor(kibanaUrl, username, password) {
+        this.baseUrl = kibanaUrl.replace(/\/$/, "");
+        const credentials = Buffer.from(`${username}:${password}`).toString("base64");
+        this.headers = {
+            Authorization: `Basic ${credentials}`,
+            "kbn-xsrf": "true",
+            "x-elastic-internal-origin": "kibana",
+            "Content-Type": "application/json",
+        };
+    }
+    async request(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        const res = await fetch(url.toString(), { headers: this.headers });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Kibana API error ${res.status}: ${body}`);
+        }
+        return res.json();
+    }
+    async getServices(start, end, environment) {
+        return this.request("/internal/apm/services", {
+            start,
+            end,
+            environment: environment ?? "ENVIRONMENT_ALL",
+            probability: "1",
+            documentType: "transactionMetric",
+            rollupInterval: "60m",
+            kuery: "",
+            useDurationSummary: "true",
+        });
+    }
+    async getServiceOverview(serviceName, start, end, environment) {
+        const env = environment ?? "ENVIRONMENT_ALL";
+        const base = `/internal/apm/services/${encodeURIComponent(serviceName)}`;
+        const common = {
+            start,
+            end,
+            environment: env,
+            probability: "1",
+            documentType: "transactionMetric",
+            rollupInterval: "60m",
+            kuery: "",
+        };
+        const [transactions, errors] = await Promise.all([
+            this.request(`${base}/transactions/groups/main_statistics`, {
+                ...common,
+                transactionType: "request",
+                latencyAggregationType: "avg",
+                useDurationSummary: "true",
+            }),
+            this.request(`${base}/errors/groups/main_statistics`, {
+                start,
+                end,
+                environment: env,
+                kuery: "",
+            }),
+        ]);
+        return { transactions, errors };
+    }
+    async getErrors(serviceName, start, end, environment) {
+        return this.request(`/internal/apm/services/${encodeURIComponent(serviceName)}/errors/groups/main_statistics`, {
+            start,
+            end,
+            environment: environment ?? "ENVIRONMENT_ALL",
+            kuery: "",
+        });
+    }
+    async getTransactions(serviceName, start, end, transactionType = "request", environment) {
+        return this.request(`/internal/apm/services/${encodeURIComponent(serviceName)}/transactions/groups/main_statistics`, {
+            start,
+            end,
+            transactionType,
+            environment: environment ?? "ENVIRONMENT_ALL",
+            latencyAggregationType: "avg",
+            documentType: "transactionMetric",
+            rollupInterval: "60m",
+            kuery: "",
+            useDurationSummary: "true",
+        });
+    }
+}

package/dist/tools/errors.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export function registerErrorTools(server, client) {
+    server.tool("get_errors", "특정 서비스의 에러 그룹을 조회합니다", {
+        serviceName: z.string().describe("서비스 이름"),
+        start: z.string().describe("조회 시작 시간 (ISO 8601)"),
+        end: z.string().describe("조회 종료 시간 (ISO 8601)"),
+        environment: z.string().optional().describe("환경 필터"),
+    }, async ({ serviceName, start, end, environment }) => {
+        const data = await client.getErrors(serviceName, start, end, environment);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/services.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export function registerServiceTools(server, client) {
+    server.tool("list_services", "APM에 등록된 서비스 목록을 조회합니다", {
+        start: z.string().describe("조회 시작 시간 (ISO 8601, e.g. 2026-04-01T00:00:00Z)"),
+        end: z.string().describe("조회 종료 시간 (ISO 8601)"),
+        environment: z.string().optional().describe("환경 필터 (e.g. production, staging)"),
+    }, async ({ start, end, environment }) => {
+        const data = await client.getServices(start, end, environment);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool("get_service_overview", "특정 서비스의 트랜잭션 성능과 에러 요약을 조회합니다", {
+        serviceName: z.string().describe("서비스 이름"),
+        start: z.string().describe("조회 시작 시간 (ISO 8601)"),
+        end: z.string().describe("조회 종료 시간 (ISO 8601)"),
+        environment: z.string().optional().describe("환경 필터"),
+    }, async ({ serviceName, start, end, environment }) => {
+        const data = await client.getServiceOverview(serviceName, start, end, environment);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/transactions.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export function registerTransactionTools(server, client) {
+    server.tool("get_transactions", "특정 서비스의 트랜잭션 성능 통계를 조회합니다", {
+        serviceName: z.string().describe("서비스 이름"),
+        start: z.string().describe("조회 시작 시간 (ISO 8601)"),
+        end: z.string().describe("조회 종료 시간 (ISO 8601)"),
+        transactionType: z
+            .string()
+            .default("request")
+            .describe("트랜잭션 타입 (e.g. request, messaging)"),
+        environment: z.string().optional().describe("환경 필터"),
+    }, async ({ serviceName, start, end, transactionType, environment }) => {
+        const data = await client.getTransactions(serviceName, start, end, transactionType, environment);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "elastic-apm-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for monitoring Elastic APM via Kibana API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "elastic-apm-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "node dist/index.js",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "elastic",
+    "apm",
+    "kibana",
+    "monitoring"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kimjunyoung90/elastic-apm-mcp-server.git"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}