# Directory Structure
```
├── .DS_Store
├── .gitignore
├── Dockerfile
├── git-upload.sh
├── issue-template.md
├── LICENSE
├── llms-install.md
├── logo-instructions.txt
├── mysql-mcp-logo.png
├── package-lock.json
├── package.json
├── README.md
├── src
│ └── index.ts
├── submission-checklist.md
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
node_modules/
build/
*.log
.env*
.DS_Store
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# MySQL MCP Server
A powerful MCP server that provides direct access to MySQL databases. This server enables AI agents to interact with MySQL databases, execute SQL queries, and manage database content through a simple interface.
## Features
### Resources
- Access notes stored in the database via `note:///{id}` URIs
- Each note has a title and content
- Plain text mime type for simple content access
### Tools
- `create_note` - Create new text notes in the database
- Takes title and content as required parameters
- Stores note in the MySQL database
- `list_tables` - List all tables in the connected database
- `count_tables` - Get the total number of tables in the database
- `search_tables` - Search for tables using LIKE pattern
- `describe_table` - Get the structure of a specific table
- `execute_sql` - Execute custom SQL queries
## Prerequisites
- Node.js 18 or higher
- MySQL server installed and running
- A database with appropriate permissions
## Setup
1. Clone this repository:
```bash
git clone [email protected]:LeonMelamud/mysql-mcp.git
cd mysql-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Create a `.env` file in the root directory with your MySQL connection details:
```
MYSQL_HOST=localhost
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database
```
4. Build the server:
```bash
npm run build
```
## Installation
### For Claude Desktop
Add the server config to your Claude Desktop configuration file:
On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/path/to/mysql-server/build/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "your_username",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database"
}
}
}
}
```
### For Cline
Add the server config to your Cline MCP settings file:
On MacOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
On Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
```json
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/path/to/mysql-server/build/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "your_username",
"MYSQL_PASSWORD": "your_password",
"MYSQL_DATABASE": "your_database"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Usage Examples
Once installed, you can use the MySQL MCP server in your conversations with Claude:
### List all tables in the database
```
Please list all the tables in my MySQL database.
```
### Execute a SQL query
```
Run this SQL query: SELECT * FROM users LIMIT 5
```
### Create a note
```
Create a note titled "Meeting Notes" with the content "Discussed project timeline and assigned tasks."
```
## Development
For development with auto-rebuild:
```bash
npm run watch
```
### Debugging
Use the MCP Inspector to debug the server:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
## License
MIT
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
FROM node:20-slim
# Install MySQL client for connectivity testing
RUN apt-get update && apt-get install -y default-mysql-client && rm -rf /var/lib/apt/lists/*
WORKDIR /app
# Copy package files
COPY package*.json ./
# Install dependencies
RUN npm install
# Copy source code
COPY . .
# Build TypeScript code
RUN npm run build
# Expose the default MCP port
EXPOSE 3308
# Set environment variables
ENV NODE_ENV=production
# Run the MCP server
CMD ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "mysql-server",
"version": "0.1.0",
"description": "local mysql 3308",
"private": true,
"license": "MIT",
"type": "module",
"bin": {
"mysql-server": "./build/index.js"
},
"files": [
"build"
],
"scripts": {
"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
"prepare": "npm run build",
"watch": "tsc --watch",
"inspector": "npx @modelcontextprotocol/inspector build/index.js"
},
"dependencies": {
"@modelcontextprotocol/sdk": "0.6.0",
"dotenv": "^16.4.7",
"mysql2": "^3.11.5"
},
"devDependencies": {
"@types/node": "^20.11.24",
"typescript": "^5.3.3"
}
}
```
--------------------------------------------------------------------------------
/git-upload.sh:
--------------------------------------------------------------------------------
```bash
#!/bin/bash
# Initialize Git repository (if not already done)
if [ ! -d .git ]; then
echo "Initializing Git repository..."
git init
else
echo "Git repository already initialized."
fi
# Add all files to the repository
echo "Adding files to Git repository..."
git add .
# Commit the changes
echo "Committing changes..."
git commit -m "Initial commit of MySQL MCP server"
# Set the remote origin to the GitHub repository
echo "Setting remote origin..."
git remote add origin [email protected]:LeonMelamud/mysql-mcp.git
# Get the current branch name
BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "main")
if [ "$BRANCH" = "" ]; then
BRANCH="main"
fi
# Push the changes to GitHub
echo "Pushing to GitHub on branch $BRANCH..."
git push -u origin $BRANCH
echo "Done! Repository uploaded to GitHub."
```
--------------------------------------------------------------------------------
/logo-instructions.txt:
--------------------------------------------------------------------------------
```
# MySQL MCP Server Logo Instructions
To complete the submission to the MCP marketplace, you'll need to create a 400x400 PNG logo for your MySQL MCP server.
## Logo Requirements
- Size: 400x400 pixels
- Format: PNG with transparency
- Content: A visual representation of MySQL and MCP integration
## Suggested Design
1. Use the MySQL dolphin logo as inspiration
2. Combine it with the MCP logo or a database icon
3. Use blue colors to match MySQL's branding
4. Keep the design simple and recognizable at smaller sizes
## Tools for Creating the Logo
- Adobe Illustrator or Photoshop
- Figma
- Canva
- GIMP (free alternative)
## File Naming and Location
Save the completed logo as `mysql-mcp-logo.png` in the root directory of the MySQL MCP server project.
## Example Logo Description
A blue MySQL dolphin icon with a database symbol, surrounded by a circular MCP-style connector icon, all on a transparent background.
```
--------------------------------------------------------------------------------
/issue-template.md:
--------------------------------------------------------------------------------
```markdown
# MySQL MCP Server Submission
I'd like to submit the MySQL MCP server to be included in Cline's MCP Marketplace.
## GitHub Repo URL
[https://github.com/LeonMelamud/mysql-mcp](https://github.com/LeonMelamud/mysql-mcp)
## Logo Image
## Reason for Addition
The MySQL MCP server provides a powerful interface for AI agents like Cline to interact directly with MySQL databases. This enables users to:
1. **Query databases directly**: Users can ask Cline to retrieve information from their databases without writing SQL queries themselves.
2. **Manage database content**: The server allows creating, reading, updating, and deleting database records through natural language commands.
3. **Explore database structure**: Users can easily explore their database schema, list tables, and understand table structures.
4. **Execute custom SQL**: For advanced users, the server supports executing custom SQL queries while maintaining the security of parameterized queries.
This MCP server bridges the gap between natural language interfaces and database operations, making database interactions more accessible to users without SQL expertise while still providing powerful capabilities for advanced users.
## Testing Confirmation
- [x] Verified all functions work correctly
- [x] list_tables
- [x] count_tables
- [x] search_tables
- [x] describe_table
- [x] execute_sql
- [x] create_note
- [x] Resource access (note:///{id})
## Additional Notes
The server includes comprehensive error handling and security measures to prevent SQL injection. It's designed to be easily configurable through environment variables, making it adaptable to different MySQL server configurations.
```
--------------------------------------------------------------------------------
/submission-checklist.md:
--------------------------------------------------------------------------------
```markdown
# MCP Marketplace Submission Checklist
Use this checklist to ensure your MySQL MCP server is ready for submission to the MCP marketplace.
## Required Items
- [x] Verified all functions work correctly
- [x] list_tables
- [x] count_tables
- [x] search_tables
- [x] describe_table
- [x] execute_sql
- [x] create_note
- [x] Resource access (note:///{id})
- [x] Updated README.md with clear installation instructions
- [x] Features section
- [x] Prerequisites section
- [x] Setup instructions
- [x] Installation instructions for Claude Desktop and Cline
- [x] Usage examples
- [x] Development and debugging information
- [x] Created llms-install.md with additional guidance for AI agents
- [x] Detailed installation steps
- [x] Troubleshooting section
- [x] Testing instructions
- [X] Created a 400x400 PNG logo
- [X] Logo represents MySQL and MCP integration
- [X] Logo is visually appealing and recognizable
- [X] Logo is saved as mysql-mcp-logo.png in the root directory
## Submission Process
1. [ ] Create a new issue in the [MCP Marketplace repository](https://github.com/cline/mcp-marketplace)
2. [ ] Include the following information in the issue:
- [ ] GitHub Repo URL: Link to your MySQL MCP server repository (https://github.com/LeonMelamud/mysql-mcp)
- [ ] Logo Image: Attach the 400x400 PNG logo
- [ ] Reason for Addition: Explain why your MySQL MCP server is awesome and how it benefits Cline users
3. [ ] Confirm that you have tested giving Cline just your README.md and/or llms-install.md and watched it successfully setup the server
## Final Checks
- [ ] Code is well-documented and follows best practices
- [ ] All dependencies are properly listed in package.json
- [ ] Server handles errors gracefully
- [ ] Environment variables are properly documented
- [ ] No sensitive information is included in the repository
```
--------------------------------------------------------------------------------
/llms-install.md:
--------------------------------------------------------------------------------
```markdown
# MySQL MCP Server Installation Guide for AI Agents
This guide provides specific instructions for AI agents like Cline to help users install and configure the MySQL MCP server.
## Prerequisites
Before installing this MCP server, ensure the user has:
1. Node.js 18 or higher installed
2. A MySQL server installed and running
3. A database with appropriate permissions
4. The necessary database credentials (host, username, password, database name)
## Installation Steps
1. First, check if the user has a MySQL server running:
```bash
mysql --version
```
2. If MySQL is not installed, guide the user to install it based on their operating system.
3. Clone the repository:
```bash
git clone [email protected]:LeonMelamud/mysql-mcp.git
cd mysql-mcp
```
4. Install dependencies:
```bash
npm install
```
5. Create a `.env` file with the MySQL connection details:
```
MYSQL_HOST=localhost
MYSQL_USER=username
MYSQL_PASSWORD=password
MYSQL_DATABASE=database_name
```
6. Build the server:
```bash
npm run build
```
7. Add the server configuration to the appropriate config file:
For Claude Desktop:
```json
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/absolute/path/to/mysql-mcp/build/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "username",
"MYSQL_PASSWORD": "password",
"MYSQL_DATABASE": "database_name"
}
}
}
}
```
For Cline:
```json
{
"mcpServers": {
"mysql": {
"command": "node",
"args": ["/absolute/path/to/mysql-mcp/build/index.js"],
"env": {
"MYSQL_HOST": "localhost",
"MYSQL_USER": "username",
"MYSQL_PASSWORD": "password",
"MYSQL_DATABASE": "database_name"
},
"disabled": false,
"autoApprove": []
}
}
}
```
## Troubleshooting
If the user encounters issues:
1. Verify MySQL is running:
```bash
sudo systemctl status mysql # For Linux
brew services list # For macOS
```
2. Test the MySQL connection:
```bash
mysql -u username -p -h localhost database_name
```
3. Check the .env file has the correct credentials
4. Ensure the build directory exists and contains the compiled JavaScript files:
```bash
ls -la build/
```
5. Try running the server directly to see any error messages:
```bash
node build/index.js
```
## Testing the Installation
Once installed, you can verify the installation by asking the user to:
1. Restart Cline or Claude Desktop
2. Ask you to list all tables in their database
3. Create a test note
4. Access the created note
Example commands to test:
```
Please list all tables in my MySQL database.
Create a note titled "Test Note" with content "This is a test note."
Show me the note I just created.
```
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import mysql from 'mysql2/promise';
import dotenv from 'dotenv';
// Load environment variables from .env file
dotenv.config();
type Note = { title: string, content: string };
// Create MySQL connection pool
const pool = mysql.createPool({
host: process.env.MYSQL_HOST,
user: process.env.MYSQL_USER,
password: process.env.MYSQL_PASSWORD,
database: process.env.MYSQL_DATABASE,
});
// Initialize database table
async function initDatabase() {
try {
const connection = await pool.getConnection();
await connection.execute(`
CREATE TABLE IF NOT EXISTS notes (
id INT AUTO_INCREMENT PRIMARY KEY,
title VARCHAR(255) NOT NULL,
content TEXT NOT NULL
)
`);
connection.release();
} catch (error) {
console.error('Failed to initialize database:', error);
process.exit(1);
}
}
const server = new Server(
{
name: "mysql-server",
version: "0.1.0",
},
{
capabilities: {
resources: {},
tools: {},
},
}
);
server.setRequestHandler(ListResourcesRequestSchema, async () => {
const [rows] = await pool.execute('SELECT id, title FROM notes');
return {
resources: (rows as any[]).map(note => ({
uri: `note:///${note.id}`,
mimeType: "text/plain",
name: note.title,
description: `A text note: ${note.title}`
}))
};
});
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const url = new URL(request.params.uri);
const id = url.pathname.replace(/^\//, '');
const [rows] = await pool.execute('SELECT * FROM notes WHERE id = ?', [id]);
const notes = rows as any[];
if (notes.length === 0) {
throw new Error(`Note ${id} not found`);
}
return {
contents: [{
uri: request.params.uri,
mimeType: "text/plain",
text: notes[0].content
}]
};
});
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "create_note",
description: "Create a new note",
inputSchema: {
type: "object",
properties: {
title: {
type: "string",
description: "Title of the note"
},
content: {
type: "string",
description: "Text content of the note"
}
},
required: ["title", "content"]
}
},
{
name: "list_tables",
description: "List all tables in the database",
inputSchema: {
type: "object",
properties: {},
required: []
}
},
{
name: "count_tables",
description: "Get the total number of tables in the database",
inputSchema: {
type: "object",
properties: {},
required: []
}
},
{
name: "search_tables",
description: "Search for tables using LIKE pattern",
inputSchema: {
type: "object",
properties: {
pattern: {
type: "string",
description: "LIKE pattern to search for (e.g. '%bill%')"
}
},
required: ["pattern"]
}
},
{
name: "describe_table",
description: "Get the structure of a table",
inputSchema: {
type: "object",
properties: {
table: {
type: "string",
description: "Name of the table to describe"
}
},
required: ["table"]
}
},
{
name: "execute_sql",
description: "Execute a SQL query",
inputSchema: {
type: "object",
properties: {
query: {
type: "string",
description: "SQL query to execute"
},
params: {
type: "array",
description: "Query parameters (optional)",
items: {
type: "string"
}
}
},
required: ["query"]
}
}
]
};
});
server.setRequestHandler(CallToolRequestSchema, async (request) => {
switch (request.params.name) {
case "create_note": {
const title = String(request.params.arguments?.title);
const content = String(request.params.arguments?.content);
if (!title || !content) {
throw new Error("Title and content are required");
}
const [result] = await pool.execute(
'INSERT INTO notes (title, content) VALUES (?, ?)',
[title, content]
);
const id = (result as any).insertId;
return {
content: [{
type: "text",
text: `Created note ${id}: ${title}`
}]
};
}
case "list_tables": {
const [rows] = await pool.execute('SHOW TABLES');
const tables = (rows as any[]).map(row => Object.values(row)[0]);
return {
content: [{
type: "text",
text: `Tables in database:\n${tables.join('\n')}`
}]
};
}
case "count_tables": {
try {
const [rows] = await pool.execute('SHOW TABLES');
const count = (rows as any[]).length;
return {
content: [{
type: "text",
text: `Total number of tables: ${count}`
}]
};
} catch (error: any) {
const errorMessage = error?.message || 'Unknown error occurred';
throw new Error(`Failed to count tables: ${errorMessage}`);
}
}
case "search_tables": {
const pattern = String(request.params.arguments?.pattern);
if (!pattern) {
throw new Error("Search pattern is required");
}
const [rows] = await pool.execute('SHOW TABLES WHERE Tables_in_' + process.env.MYSQL_DATABASE + ' LIKE ?', [pattern]);
const tables = (rows as any[]).map(row => Object.values(row)[0]);
return {
content: [{
type: "text",
text: `Tables matching pattern '${pattern}':\n${tables.join('\n')}`
}]
};
}
case "describe_table": {
const table = String(request.params.arguments?.table);
if (!table) {
throw new Error("Table name is required");
}
// First verify the table exists
const [tables] = await pool.execute('SHOW TABLES');
const tableExists = (tables as any[]).some(row => Object.values(row)[0] === table);
if (!tableExists) {
throw new Error(`Table '${table}' does not exist`);
}
// Get table structure
const [rows] = await pool.execute(`DESCRIBE ${table}`);
return {
content: [{
type: "text",
text: JSON.stringify(rows, null, 2)
}]
};
}
case "execute_sql": {
const query = String(request.params.arguments?.query);
const params = request.params.arguments?.params || [];
if (!query) {
throw new Error("SQL query is required");
}
try {
// Execute the query with optional parameters
const [result] = await pool.execute(query, params);
return {
content: [{
type: "text",
text: JSON.stringify(result, null, 2)
}]
};
} catch (error: any) {
const errorMessage = error?.message || 'Unknown error occurred';
throw new Error(`Failed to execute SQL: ${errorMessage}`);
}
}
default:
throw new Error("Unknown tool");
}
});
async function main() {
try {
await initDatabase();
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('MySQL MCP server running on stdio');
} catch (error) {
console.error("Server error:", error);
process.exit(1);
}
}
main().catch((error) => {
console.error("Server error:", error);
process.exit(1);
});
```