{"_id":"@abeqqal_marouane/mysql-mcp-server","_rev":"3-e706092602f483151d5bac5fdd602ab4","name":"@abeqqal_marouane/mysql-mcp-server","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@abeqqal_marouane/mysql-mcp-server","version":"1.0.0","keywords":["mcp","model-context-protocol","mysql","ai","agent","llm","eventscribe"],"author":{"name":"Marouane Abeqqal"},"license":"MIT","_id":"@abeqqal_marouane/mysql-mcp-server@1.0.0","maintainers":[{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"}],"homepage":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server#readme","bugs":{"url":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server/issues"},"bin":{"mysql-mcp-server":"build/index.js"},"dist":{"shasum":"58c5c77042d3d03de74eb5d0061c03d0d9546100","tarball":"https://registry.npmjs.org/@abeqqal_marouane/mysql-mcp-server/-/mysql-mcp-server-1.0.0.tgz","fileCount":3,"integrity":"sha512-mLPqXCiU1m7NUHKTdD4PU5qyhMKjoElVFTnNPT/s9zLDpyehStot4a7zSYZ9UXRaLHvl1fvHJc2VeFNzf4bV5A==","signatures":[{"sig":"MEUCIQClFj4ws5vX9ccsJobcodQYYQ0nO2YKfU/bg+XhqRM2KgIgSc+6TjttekPFB7g3TTsZ7xx5515yJoTpc1QnhK0fXd0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13405},"main":"build/index.js","gitHead":"08a1adaca45c4e60319440a88c25501c5130bb7c","scripts":{"build":"tsc","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"},"repository":{"url":"git+https://github.com/AbeqqalMarouane/MySQL-MCP-Server.git","type":"git"},"_npmVersion":"10.7.0","description":"A general-purpose, secure Model Context Protocol (MCP) server for MySQL databases.","directories":{},"_nodeVersion":"20.15.1","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","mysql2":"^3.10.1","@modelcontextprotocol/sdk":"^1.15.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.2","@types/node":"^20.14.9"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-server_1.0.0_1754326576676_0.47693001503988497","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abeqqal_marouane/mysql-mcp-server","version":"1.0.1","keywords":["mcp","model-context-protocol","mysql","ai","agent","llm","eventscribe"],"author":{"name":"Marouane Abeqqal"},"license":"MIT","_id":"@abeqqal_marouane/mysql-mcp-server@1.0.1","maintainers":[{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"}],"homepage":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server#readme","bugs":{"url":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server/issues"},"bin":{"mysql-mcp-server":"build/index.js"},"dist":{"shasum":"a6c4bb3f72522f4aae71b19b5c4d7b80a2e6b22e","tarball":"https://registry.npmjs.org/@abeqqal_marouane/mysql-mcp-server/-/mysql-mcp-server-1.0.1.tgz","fileCount":3,"integrity":"sha512-vWb26toidWfP3CxnoF93dhcZz3PS/dKBieYlox/ERvmlOgE6w8qMBFwH3f/R4LTgQCJhzpbAbq32rYIj9eQW3Q==","signatures":[{"sig":"MEUCIQDzWQ2NpR+dlr7FMIMQcPL4Ib9D9XM3b0SmlCEw/LbBxwIgDUnRnHH6kn/jNT3fv5HHdxn5IFJGPmNzArJ1HRSbwiY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":13292},"main":"build/index.js","gitHead":"08a1adaca45c4e60319440a88c25501c5130bb7c","scripts":{"build":"tsc","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"},"repository":{"url":"git+https://github.com/AbeqqalMarouane/MySQL-MCP-Server.git","type":"git"},"_npmVersion":"10.7.0","description":"A general-purpose, secure Model Context Protocol (MCP) server for MySQL databases.","directories":{},"_nodeVersion":"20.15.1","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","mysql2":"^3.10.1","@modelcontextprotocol/sdk":"^1.15.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.2","@types/node":"^20.14.9"},"_npmOperationalInternal":{"tmp":"tmp/mysql-mcp-server_1.0.1_1754329071605_0.9091938513899998","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@abeqqal_marouane/mysql-mcp-server","version":"1.0.2","description":"A general-purpose, secure Model Context Protocol (MCP) server for MySQL databases.","main":"build/index.js","bin":{"mysql-mcp-server":"build/index.js"},"scripts":{"build":"tsc","start":"node build/index.js","prepublishOnly":"npm run build"},"repository":{"type":"git","url":"git+https://github.com/AbeqqalMarouane/MySQL-MCP-Server.git"},"keywords":["mcp","model-context-protocol","mysql","ai","agent","llm","eventscribe"],"author":{"name":"Marouane Abeqqal"},"license":"MIT","bugs":{"url":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server/issues"},"homepage":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server#readme","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.15.1","dotenv":"^16.4.5","mysql2":"^3.10.1","zod":"^3.23.8"},"devDependencies":{"@types/node":"^20.14.9","typescript":"^5.5.2"},"_id":"@abeqqal_marouane/mysql-mcp-server@1.0.2","gitHead":"1ddecb57c6777bdfacdd82164ccaf742ae44b2b0","_nodeVersion":"20.15.1","_npmVersion":"10.7.0","dist":{"integrity":"sha512-0P45GM4Tvl0BNUZB5mrzFzrbg1VuLBzvZ0dDRzDdwKiV7MdsKP8EyUMIGd6drbKY8Hp+iMDEbhWWMZ9c8QTKZw==","shasum":"4adb6db6eac6907a9087e67dae7b1d6f2dd6984a","tarball":"https://registry.npmjs.org/@abeqqal_marouane/mysql-mcp-server/-/mysql-mcp-server-1.0.2.tgz","fileCount":3,"unpackedSize":13300,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCDsWZhRflk01KHrjBV9NDefDdpY4BYvkLF/hO4B6O4zwIhAPKGRCeqQQcar2jBXPbBKIp6txbrkhLW2x8370B+H7jl"}]},"_npmUser":{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"},"directories":{},"maintainers":[{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mysql-mcp-server_1.0.2_1754393490713_0.11136894901776517"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-04T16:56:16.546Z","modified":"2025-08-05T11:31:31.095Z","1.0.0":"2025-08-04T16:56:16.859Z","1.0.1":"2025-08-04T17:37:51.798Z","1.0.2":"2025-08-05T11:31:30.918Z"},"bugs":{"url":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server/issues"},"author":{"name":"Marouane Abeqqal"},"license":"MIT","homepage":"https://github.com/AbeqqalMarouane/MySQL-MCP-Server#readme","keywords":["mcp","model-context-protocol","mysql","ai","agent","llm","eventscribe"],"repository":{"type":"git","url":"git+https://github.com/AbeqqalMarouane/MySQL-MCP-Server.git"},"description":"A general-purpose, secure Model Context Protocol (MCP) server for MySQL databases.","maintainers":[{"name":"abeqqal_marouane","email":"marouane.abeqqal@usmba.ac.ma"}],"readme":"# General-Purpose MySQL MCP Server\r\n\r\n[![npm version](https://img.shields.io/npm/v/@abeqqal_marouane/mysql-mcp-server.svg?style=for-the-badge)](https://www.npmjs.copackage/@abeqqal_marouane/mysql-mcp-server)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-black?style=for-the-badge&logo=typescript&logoColor=white)](https://wwtypescriptlang.org/)\r\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue?style=for-the-badge)](https://modelcontextprotocol.io/)\r\n[![MySQL](https://img.shields.io/badge/MySQL-4479A1?style=for-the-badge&logo=mysql&logoColor=white)](https://www.mysql.com/\r\nThis repository contains a general-purpose, secure, and efficient **Model Context Protocol (MCP)** server for MySQL databases. Iacts as a secure bridge, allowing AI agents and applications (MCP Clients) to interact with any MySQL database without needindirect credentials\r\nThis server is designed to be a standalone, reusable npm package. It was originally developed for the [EventScribe AI](https:github.com/AbeqqalMarouane/PromptEnhancing_UsingMCP) project but can be used by any MCP-compatible client\r\n## ✨ Key Feature\r\n- **Dynamic Schema Discovery**: Exposes the full database schema as an MCP `resource`, allowing AI agents to understand the structure of any database it connects to.\r\n- **Secure Read-Only Querying**: Provides a `read_only_query` MCP `tool` that strictly enforces `SELECT` statements, preventinany destructive operations and protecting your data.\r\n- **High Performance**: Uses a MySQL connection pool for efficient, high-concurrency database interactions suitable for production environments.\r\n- **Simple Configuration**: Uses a clean `.env` file in the user's home directory, keeping credentials secure and separate froclient applications.\r\n- **Graceful Shutdown**: Includes logic to cleanly close database connections when the server process is terminated\r\n## 🏗️ Architecture: The Server's Rol\r\nThis MCP server is the \"Data Layer\" in a modern agentic architecture. The client (e.g., a Next.js application) orchestrates thworkflow, while this server is the only component with direct access to the database\r\n```mermaid\r\n  graph TD\r\n    subgraph \"Client's Responsibility (e.g., EventScribe AI)\"\r\n        A[\"Client Application\"]\r\n        A -- \"Starts & Manages Process\" --> B\r\n        A -- \"Sends 'Get Schema' Request\" --> B\r\n        A -- \"Sends 'Run Query' Request\" --> B\r\n    end\r\n\r\n    subgraph \"Server's Responsibility (This Project)\"\r\n        B[\"MySQL MCP Server\"]\r\n        B -- \"Manages Connection Pool\" --> C[(MySQL Database)]\r\n        B -- \"Executes SHOW CREATE TABLE\" --> C\r\n        B -- \"Executes safe SELECT query\" --> C\r\n        C -- \"Returns SQL Results\" --> B\r\n    end\r\n\r\n    B -- \"Returns Schema as Resource\" --> A\r\n    B -- \"Returns Query Data as Tool Result\" --> A\r\n```\r\n## 🚀 Installation & Usage Guide for Users\r\nThis guide explains how to install and use the server as an npm package. For instructions on how to contribute to the code, see the \"For Developers\" section below\r\n### Step 1: Installation\r\nIn your client project (e.g., your Next.js app), install the package from npm\r\n```bash\r\nnpm install @abeqqal_marouane/mysql-mcp-server\r\n```\r\n### Step 2: Configuration for Users\r\nThis server requires a configuration file to securely connect to your database\r\nCreate a dedicated folder in your user home directory\r\n- On Windows (PowerShell): `mkdir ~/.mysql-mcp-server`\r\n- On macOS/Linux (Terminal): `mkdir -p ~/.mysql-mcp-server\r\nCreate the configuration file. Inside that new folder, create a file named `config.env`\r\nAdd your database credentials to the `config.env` file with the following format\r\n```env\r\n# ~/.mysql-mcp-server/config.en\r\nDB_HOST=localhost\r\nDB_USER=your_mysql_user\r\nDB_PASSWORD=your_mysql_password\r\nDB_NAME=your_database_name\r\nDB_PORT=3306\r\n```\r\nThe server will automatically find and load this file every time it starts\r\n### Step 3: Usage\r\nThis server is designed to be launched and controlled by an MCP client\r\n#### In an MCP Client Application (e.g., Next.js)\r\nConfigure your client's `StdioClientTransport` to use the command provided by this package. Note that you no longer need filpaths or `npm start`\r\n```javascript\r\n// In your client application code\r\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\"\r\nconst transport = new StdioClientTransport({\r\n  command: \"mysql-mcp-server\",\r\n  args: []\r\n})\r\n// ... then connect your MCP client to this transport.\r\n```\r\n#### For Quick Testing with MCP Inspector\r\nYou can test the server directly from your terminal, without needing to clone the repository\r\nFirst, install the package globally to make the command available everywhere\r\n```bash\r\nnpm install -g @abeqqal_marouane/mysql-mcp-server\r\n```\r\nMake sure you have created the `config.env` file as described in the \"Configuration\" step above\r\nRun the server with the Inspector\r\n```bash\r\nnpx -- @modelcontextprotocol/inspector mysql-mcp-server\r\n```\r\n## 📖 Exposed MCP Capabilities\r\nThis server exposes two primary capabilities to any connected client\r\n### Resource: schema\r\n- **URI**: `mysql://schemas`\r\n- **Description**: Returns the full `CREATE TABLE` SQL statements for all tables in the connected database. This allows an Aagent to learn the complete structure of the database.\r\n- **Usage (in a client)**\r\n```typescript\r\nmcpClient.readResource({ uri: \"mysql://schemas\" })\r\n```\r\n### Tool: read_only_query\r\n- **Name**: `read_only_query`\r\n- **Description**: Executes a SQL query against the database.\r\n- **Input Schema**: `{ sql: string }`\r\n- **Security**: The tool contains a vital security check. It will only execute queries that begin with `SELECT`. Any other command (UPDATE, DELETE, INSERT, DROP, etc.) will be rejected with an error.\r\n- **Usage (in a client)**\r\n```typescript\r\nmcpClient.callTool({\r\n  name: \"read_only_query\",\r\n  arguments: { sql: \"SELECT * FROM events LIMIT 10\" }\r\n});\r\n```\r\n## 👨‍💻 For Developers / Contributing\r\nIf you want to modify or contribute to this server, follow these steps\r\n### Clone the repository\r\n```bash\r\ngit clone https://github.com/AbeqqalMarouane/MySQL-MCP-Server.git\r\ncd MySQL-MCP-Server\r\n```\r\n### Install dependencies\r\n```bash\r\nnpm install\r\n```\r\n### Create a local `.env` file for development\r\nAs described in the Configuration section\r\n### Build the TypeScript code\r\n```bash\r\nnpm run build\r\n```\r\nContributions are welcome! Please feel free to fork the repository, make your changes, and submit a pull request\r\n## 📄 License\r\nThis project is licensed under the MIT License.","readmeFilename":"README.md"}