Db MCP

🚀 db-mcp

A Model Context Protocol (MCP) server for connecting to and querying MySQL, Redis, and MongoDB databases.

📸 Screenshots of Usage

Example of Redis Query

Example of MySQL Statistical Query

Example of MongoDB Statistical Query

✨ Features

• ✅ MySQL Support: Connect, query, and execute SQL statements.
• ✅ Redis Support: Key-value operations, hash operations, and pattern matching.
• ✅ MongoDB Support: Document querying, insertion, updating, and deletion.
• 🔒 Security Modes: Supports three security levels: read-only mode, restricted mode, and full access mode.

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0 or yarn >= 1.22.0

Installation Steps

# Clone the repository
git clone git@github_pig:wannanbigpig/db-mcp.git
cd db-mcp

# Install dependencies
npm install

# Build the project
npm run build

Verify Installation

After the build is complete, you can run the following commands to verify the installation:

# Run in development mode (for testing)
npm run dev

# Or directly run the built file
node dist/index.js

If you see the prompt "db-mcp server has started", the installation is successful.

Configure Database Connection (Optional)

After installation, you can choose to configure the database connection:

1. Copy the example configuration file:

cp config.json.example config.json

2. Edit config.json and fill in your database connection information.

For detailed configuration instructions, please refer to the Database Connection Configuration section.

Troubleshooting

If you encounter problems during installation or operation:

1. Check the Node.js version:

node --version  # Should be >= 18.0.0

2. Clean and reinstall:

rm -rf node_modules package-lock.json
npm install
npm run build

3. Check the build output:

ls -la dist/  # Should see the compiled .js files

💻 Usage

db-mcp is a standard MCP (Model Context Protocol) server that can be used in any MCP-supported client, including but not limited to:

• Cursor - An AI code editor.
• Claude Desktop - Anthropic's Claude desktop application.
• Other MCP-supported clients

Configure the MCP Server

Add the db-mcp server configuration to your MCP client configuration file. The configuration format varies by client:

Example Configuration for Cursor

Add the following to Cursor's settings file (usually ~/.cursor/mcp.json or the MCP configuration in Cursor settings):

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/path/to/db-mcp/dist/index.js"],
      "env": {
        "DB_MCP_SECURITY_MODE": "read_only",
        "DB_MCP_CONFIG_PATH": "/path/to/config.json"
      }
    }
  }
}

Example Configuration for Claude Desktop

Add the following to Claude Desktop's configuration file (usually ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/path/to/db-mcp/dist/index.js"],
      "env": {
        "DB_MCP_SECURITY_MODE": "read_only"
      }
    }
  }
}

Note: Replace /path/to/db-mcp/dist/index.js with your actual installation path.

Pre-configure Database Connections

Supports pre-configuring database connections through config.json or environment variables. Simply copy config.json.example to config.json and edit it.

Examples of environment variables: MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, REDIS_HOST, MONGODB_URL, etc.

Security Modes

Set through the DB_MCP_SECURITY_MODE environment variable or the set_security_mode tool:

• read_only (default): Only query operations are allowed.
• restricted: Allows queries and some modifications, prohibits dangerous operations (DROP, TRUNCATE, ALTER TABLE, etc.).
• full_access: Allows all operations, including table structure changes.

Development Mode

npm run dev

📚 Database Connection Configuration

Pre-configured Connections (Recommended)

Pre-configure database connections through config.json or environment variables. The server will automatically connect when starting.

Example MySQL Configuration:

{
  "databases": {
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "user": "root",
      "password": "your_password",
      "database": "mydb",
      "pool": { "min": 2, "max": 10, "idleTimeout": 60000 }
    }
  }
}

Example Redis Configuration:

{
  "databases": {
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "your_password",
      "db": 0
    }
  }
}

Example MongoDB Configuration:

{
  "databases": {
    "mongodb": {
      "url": "mongodb://localhost:27017",
      "database": "mydb"
    }
  }
}

Dynamic Connections

You can also connect dynamically through tools. Use the *_connect tools to establish connections and *_disconnect to disconnect.

🛠️ Available Tools

MySQL Tools

mysql_connect

Connect to a MySQL database (supports connection pooling). If already connected through pre-configuration, this tool will reconnect.

Parameters:

• host (required): MySQL host address.
• port (optional): MySQL port, default is 3306.
• user (required): MySQL username.
• password (required): MySQL password.
• database (optional): Database name.
• usePool (optional): Whether to use a connection pool, default is false.
• pool (optional): Connection pool configuration.
  • min: Minimum number of connections, default is 2.
  • max: Maximum number of connections, default is 10.
  • idleTimeout: Idle timeout in milliseconds, default is 60000.

mysql_query

Execute MySQL SQL statements (supports all SQL operations, including table structure changes).

Parameters:

• sql (required): SQL statement.
• params (optional): Array of SQL parameters.

Examples:

{ "sql": "SELECT * FROM users WHERE id = ?", "params": [1] }
{ "sql": "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100))" }
{ "sql": "ALTER TABLE users ADD COLUMN age INT" }

mysql_insert / mysql_update / mysql_delete

More user-friendly APIs that automatically construct SQL and use parameterized queries to prevent SQL injection.

Parameters:

• table (required): Table name.
• data (required for insert/update): Data object.
• where (required for update/delete): WHERE condition object.

Examples:

{ "table": "users", "data": { "name": "John", "email": "john@example.com" } }
{ "table": "users", "data": { "name": "Jane" }, "where": { "id": 1 } }
{ "table": "users", "where": { "id": 1 } }

mysql_disconnect

Disconnect from the MySQL database.

mysql_pool_status

Get the status of the MySQL connection pool (only valid when a connection pool is used).

Parameters: None

Returns: Connection pool status information (total connections, active connections, idle connections).

Redis Tools

• redis_connect: Connect to Redis (parameters: host, port, password, db, url).
• redis_get: Get a key-value pair (parameter: key).
• redis_set: Set a key-value pair (parameters: key, value, ttl).
• redis_keys: Find matching keys (parameter: pattern).
• redis_del: Delete a key (parameter: key).
• redis_hget: Get a hash field (parameters: key, field).
• redis_hgetall: Get all hash fields (parameter: key).
• redis_disconnect: Disconnect from Redis.

MongoDB Tools

• mongodb_connect: Connect to MongoDB (parameters: url, database).
• mongodb_find: Find documents (parameters: collection, filter, limit, skip, sort).
• mongodb_find_one: Find a single document (parameters: collection, filter).
• mongodb_insert_one: Insert a single document (parameters: collection, document).
• mongodb_insert_many: Insert multiple documents (parameters: collection, documents).
• mongodb_update_one: Update a document (parameters: collection, filter, update).
• mongodb_delete_one: Delete a document (parameters: collection, filter).
• mongodb_count: Count the number of documents (parameters: collection, filter).
• mongodb_list_collections: List all collections.
• mongodb_disconnect: Disconnect from MongoDB.

Security Configuration Tools

• set_security_mode: Set the security mode (parameter: mode - read_only/restricted/full_access).
• get_security_mode: Get the current security mode.

💻 Usage Examples

MySQL

// Connect
{ "host": "localhost", "user": "root", "password": "pass", "database": "mydb" }

// Query
{ "sql": "SELECT * FROM users WHERE id = ?", "params": [1] }

// Insert
{ "table": "users", "data": { "name": "John", "email": "john@example.com" } }

Redis

// Connect
{ "host": "localhost", "port": 6379, "db": 0 }

// Operations
{ "key": "user:1", "value": "John Doe", "ttl": 3600 }
{ "key": "user:1" }
{ "pattern": "user:*" }

MongoDB

// Connect
{ "url": "mongodb://localhost:27017", "database": "mydb" }

// Operations
{ "collection": "users", "filter": { "age": { "$gte": 18 } }, "limit": 10 }
{ "collection": "users", "document": { "name": "John", "age": 30 } }

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (using tsx)
npm run dev

# Watch mode
npm run watch

📄 License

MIT

🤝 Contribution

Welcome to submit Issues and Pull Requests!