@ahngbeom/mysql-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ahngbeom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# MySQL MCP Server
+
+Claude Code에서 MySQL 데이터베이스에 접근하기 위한 **읽기 전용** MCP(Model Context Protocol) 서버입니다.
+
+## 특징
+
+- **읽기 전용**: SELECT, SHOW, DESCRIBE, EXPLAIN 쿼리만 허용
+- **안전한 연결**: Connection Pool 사용
+- **다양한 도구 제공**: 테이블 목록, 스키마 조회, 인덱스 확인, 실행 계획 분석
+
+## 설치
+
+```bash
+npm install @ahngbeom/mysql-mcp-server
+```
+
+또는 직접 빌드:
+
+```bash
+git clone https://github.com/ahngbeom/mysql-mcp-server.git
+cd mysql-mcp-server
+npm install
+npm run build
+```
+
+## 사용법
+
+### Claude Code 설정
+
+`~/.claude.json` 또는 프로젝트의 `.mcp.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "mysql": {
+      "command": "npx",
+      "args": ["@ahngbeom/mysql-mcp-server"],
+      "env": {
+        "MYSQL_HOST": "localhost",
+        "MYSQL_PORT": "3306",
+        "MYSQL_USER": "your_user",
+        "MYSQL_PASS": "your_password",
+        "MYSQL_DB": "your_database"
+      }
+    }
+  }
+}
+```
+
+### 환경 변수
+
+| 변수 | 설명 | 기본값 |
+|------|------|--------|
+| `MYSQL_HOST` | MySQL 호스트 | `localhost` |
+| `MYSQL_PORT` | MySQL 포트 | `3306` |
+| `MYSQL_USER` | 사용자 이름 | `root` |
+| `MYSQL_PASS` | 비밀번호 | (없음) |
+| `MYSQL_DB` | 데이터베이스 이름 | `mysql` |
+
+## 제공 도구
+
+### `query`
+읽기 전용 SQL 쿼리를 실행합니다.
+```
+SELECT * FROM users LIMIT 10
+```
+
+### `list_tables`
+현재 데이터베이스의 모든 테이블을 조회합니다.
+
+### `describe_table`
+테이블의 구조(컬럼, 타입, 키)를 확인합니다.
+
+### `show_indexes`
+테이블의 인덱스 정보를 조회합니다.
+
+### `show_create_table`
+테이블의 CREATE TABLE 문을 확인합니다.
+
+### `explain`
+쿼리의 실행 계획을 분석합니다.
+
+## 보안 참고사항
+
+- 이 서버는 **읽기 전용**으로 설계되었습니다
+- INSERT, UPDATE, DELETE, DROP 등의 쿼리는 차단됩니다
+- 프로덕션 환경에서는 읽기 전용 DB 사용자 계정 사용을 권장합니다
+
+## 라이선스
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Custom MySQL MCP Server
+ *
+ * MCP(Model Context Protocol)를 통해 Claude Code에서 MySQL 데이터베이스에 접근
+ *
+ * 환경변수:
+ *   MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASS, MYSQL_DB
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * Custom MySQL MCP Server
+ *
+ * MCP(Model Context Protocol)를 통해 Claude Code에서 MySQL 데이터베이스에 접근
+ *
+ * 환경변수:
+ *   MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASS, MYSQL_DB
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import mysql from "mysql2/promise";
+// 환경변수에서 연결 정보 읽기
+const config = {
+    host: process.env.MYSQL_HOST || "localhost",
+    port: parseInt(process.env.MYSQL_PORT || "3306"),
+    user: process.env.MYSQL_USER || "root",
+    password: process.env.MYSQL_PASS || "",
+    database: process.env.MYSQL_DB || "mysql",
+};
+let pool = null;
+// 연결 풀 생성
+function getPool() {
+    if (!pool) {
+        pool = mysql.createPool({
+            ...config,
+            waitForConnections: true,
+            connectionLimit: 5,
+            queueLimit: 0,
+            connectTimeout: 10000,
+        });
+    }
+    return pool;
+}
+// 쿼리 실행 (읽기 전용)
+async function executeQuery(sql) {
+    const conn = getPool();
+    const [rows] = await conn.query(sql);
+    return rows;
+}
+// MCP 서버 생성
+const server = new Server({
+    name: "mysql-mcp-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+        resources: {},
+    },
+});
+// 도구 목록 정의
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "query",
+                description: "Execute a read-only SELECT query and return results.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        sql: {
+                            type: "string",
+                            description: "The SELECT SQL query to execute (read-only)",
+                        },
+                    },
+                    required: ["sql"],
+                },
+            },
+            {
+                name: "list_tables",
+                description: "List all tables in the current database",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "describe_table",
+                description: "Show the structure of a table (columns, types, keys)",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        table: {
+                            type: "string",
+                            description: "Table name to describe",
+                        },
+                    },
+                    required: ["table"],
+                },
+            },
+            {
+                name: "show_indexes",
+                description: "Show indexes on a table",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        table: {
+                            type: "string",
+                            description: "Table name",
+                        },
+                    },
+                    required: ["table"],
+                },
+            },
+            {
+                name: "show_create_table",
+                description: "Show the CREATE TABLE statement for a table",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        table: {
+                            type: "string",
+                            description: "Table name",
+                        },
+                    },
+                    required: ["table"],
+                },
+            },
+            {
+                name: "explain",
+                description: "Show query execution plan",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        sql: {
+                            type: "string",
+                            description: "The SQL query to explain",
+                        },
+                    },
+                    required: ["sql"],
+                },
+            },
+        ],
+    };
+});
+// 도구 실행 핸들러
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "query": {
+                const sql = args.sql;
+                const trimmedSql = sql.trim().toLowerCase();
+                // 읽기 전용: SELECT, SHOW, DESCRIBE, EXPLAIN만 허용
+                const allowedPrefixes = ["select", "show", "describe", "explain"];
+                const isReadOnly = allowedPrefixes.some(prefix => trimmedSql.startsWith(prefix));
+                if (!isReadOnly) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "Error: This server is read-only. Only SELECT, SHOW, DESCRIBE, EXPLAIN queries are allowed.",
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const rows = await executeQuery(sql);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "list_tables": {
+                const rows = await executeQuery("SHOW TABLES");
+                const tables = rows.map((row) => Object.values(row)[0]);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(tables, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "describe_table": {
+                const table = args.table;
+                const rows = await executeQuery(`DESCRIBE \`${table}\``);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "show_indexes": {
+                const table = args.table;
+                const rows = await executeQuery(`SHOW INDEX FROM \`${table}\``);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "show_create_table": {
+                const table = args.table;
+                const rows = await executeQuery(`SHOW CREATE TABLE \`${table}\``);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: rows[0]?.["Create Table"] || "Table not found",
+                        },
+                    ],
+                };
+            }
+            case "explain": {
+                const sql = args.sql;
+                const rows = await executeQuery(`EXPLAIN ${sql}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(rows, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                };
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `MySQL Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// 리소스 목록 (스키마 정보 제공)
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    try {
+        const rows = await executeQuery("SHOW TABLES");
+        const tables = rows.map((row) => Object.values(row)[0]);
+        return {
+            resources: tables.map((table) => ({
+                uri: `mysql:///${config.database}/${table}`,
+                mimeType: "application/json",
+                name: `Table: ${table}`,
+                description: `Schema and sample data from ${table}`,
+            })),
+        };
+    }
+    catch {
+        return { resources: [] };
+    }
+});
+// 리소스 읽기 (테이블 스키마 + 샘플 데이터)
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const match = uri.match(/mysql:\/\/\/([^/]+)\/(.+)/);
+    if (!match) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    const [, , table] = match;
+    const structure = await executeQuery(`DESCRIBE \`${table}\``);
+    const sample = await executeQuery(`SELECT * FROM \`${table}\` LIMIT 5`);
+    const countResult = await executeQuery(`SELECT COUNT(*) as count FROM \`${table}\``);
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    table,
+                    rowCount: countResult[0]?.count,
+                    columns: structure,
+                    sampleData: sample,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// 서버 시작
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // 연결 테스트
+    try {
+        await executeQuery("SELECT 1");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`MySQL connection failed: ${message}`);
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ahngbeom/mysql-mcp-server",
+  "version": "1.0.0",
+  "description": "Read-only MySQL MCP Server for Claude Code",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mysql-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mysql",
+    "claude",
+    "claude-code",
+    "ai",
+    "database"
+  ],
+  "author": "ahngbeom",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahngbeom/mysql-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ahngbeom/mysql-mcp-server/issues"
+  },
+  "homepage": "https://github.com/ahngbeom/mysql-mcp-server#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "mysql2": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}