MCP DButils

MCP 数据库工具

MCP Database Utilities is a versatile MCP service enabling secure AI data analysis across various databases (SQLite, MySQL, PostgreSQL) with unified connections.

It acts as a secure bridge between AI systems and databases, allowing AI to read and analyze data without direct access or modification risks.

Security and Privacy: Our Priorities

MCP Database Utilities employs a security-first architecture, ideal for organizations prioritizing data protection. Our measures include:

Data Protection

• Strict Read-Only: Operations are limited to SELECT queries, preventing data modification.
• No Direct Database Access: AI interacts via our secure service, never directly connecting to databases.
• Isolated Connections: Each database connection is managed separately and strictly isolated.
• On-Demand Connections: Connections are established only when needed, disconnecting immediately after task completion.
• Automatic Timeouts: Long-running operations are automatically terminated to prevent resource abuse.

Privacy Assurance

• Local Processing: All data processing occurs on your local machine, with no data sent to external servers.
• Minimal Data Exposure: Only requested data is returned, limiting exposure.
• Credential Protection: Connection credentials are never exposed to AI models.
• Sensitive Data Masking: Passwords and connection details are automatically hidden in logs.

Enterprise-Grade Security

• SSL/TLS Support: Encrypted connections to remote databases.
• Configuration Separation: YAML configuration files eliminate interpretation risks.
• User-Controlled Access: You decide which databases are accessible.
• Secure Defaults: Security is enabled by default, requiring no extra configuration.

For technical details on our security architecture, see the Technical Guide.

Why use MCP Database Utilities?

• Universal AI Support: Works with any AI system supporting the MCP protocol.
• Multi-Database Support: Connect to SQLite, MySQL, PostgreSQL using the same interface.
• Simple Configuration: All database connections use a single YAML file.
• Advanced Features: Table browsing, schema analysis, and query execution.

System Requirements

• Python 3.10 or higher
• One of the following:
  • uvx Installation: uv package manager
  • Docker Installation: Docker Desktop
  • Smithery Installation: Node.js 14+
• Supported Databases:
  • SQLite 3.x
  • PostgreSQL 12+
  • MySQL 8+
• Supported AI Clients:
  • Claude Desktop
  • Cursor
  • Any MCP-compatible client

Getting Started

1. Installation Guide

Choose one of the following methods for installation:

Method A: Using uvx (Recommended)

This method uses uvx, part of the Python package management tool "uv". Here are the setup steps:

1. First install uv and uvx:

   On macOS or Linux:

   curl -LsSf https://astral.sh/uv/install.sh | sh

   Copy

   On Windows:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

   Copy

   After installation, verify that uv is correctly installed:

   uv --version
   # Should display something like: uv 0.5.5 (Homebrew 2024-11-27)

   Copy

2. Create a configuration file, named config.yaml, containing your database connection details:

   connections:
     postgres:
       type: postgres
       host: localhost
       port: 5432
       dbname: my_database
       user: my_user
       password: my_password

   Copy

   For advanced configuration options (SSL connections, connection pooling, etc.), please see our comprehensive Configuration Examples documentation.

3. Add this configuration to your AI client:

For JSON-based MCP clients:

• Locate and edit your client's MCP configuration file:

  • Claude Desktop (Mac): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Cline (Mac): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Cursor (Mac): ~/.cursor/mcp.json
  • Other clients: Consult your client's documentation for the MCP configuration file location.

• Add the following configuration to the JSON file:

  "dbutils": {
    "command": "uvx",
    "args": [
      "mcp-dbutils",
      "--config",
      "/full/path/to/your/config.yaml"
    ]
  }

  Copy

  Important Notes for uvx Setup:

  • Replace /full/path/to/your/config.yaml with the actual full path to your configuration file.
  • If you receive an error that uvx is not found, ensure that you have successfully completed step 1.
  • You can verify that uvx is installed by typing uv --version in your terminal.

Method B: Manual Installation using Docker

1. If you do not have Docker, install it from docker.com
2. Create a configuration file (see next section)
3. Add this configuration to your AI client:

For JSON-based MCP clients:

• Locate and edit your client's MCP configuration file:

  • Claude Desktop (Mac): ~/Library/Application Support/Claude/claude_desktop_config.json
  • Cline (Mac): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Other clients: Consult your client's documentation for the MCP configuration file location.

• Add the following configuration to the JSON file:

  "dbutils": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-v",
      "/full/path/to/your/config.yaml:/app/config.yaml",
      "-v",
      "/full/path/to/your/sqlite.db:/app/sqlite.db",  // SQLite databases only
      "mcp/dbutils",
      "--config",
      "/app/config.yaml"
    ]
  }

  Copy

  Important Notes for Docker:

  • Replace /full/path/to/your/config.yaml with the actual full path to your configuration file.
  • For SQLite databases, also replace the path for sqlite.db with your actual database path.
  • For other types of databases, remove the SQLite volume line entirely.

Method C: Using Smithery (One-Click Claude Configuration)

This method automatically installs and configures the service to Claude:

npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude

After installation, skip directly to the "Using the Service" section.

4. Using the Service

With correct installation and configuration, your AI can now:

• List tables in a database
• View table schemas
• Safely execute SQL queries (SELECT only)
• Analyze data across multiple databases

Verify that everything is working:

1. Ask your AI something like: "Can you check if I can connect to my databases?"
2. If configured correctly, the AI should reply that it can connect to the databases specified in your configuration file.
3. Try a simple command, such as: "List the tables in my database"

If you encounter issues, check:

• That your configuration file is syntactically correct
• That the database connection details are accurate
• That your AI client is correctly configured with the MCP server
• That your database is accessible from your machine

Interaction Examples

You: "Can you list all the tables in my my-postgres database?"

AI: "Let me check that for you. Here are the tables in your my-postgres database:

• customers
• products
• orders
• inventory
• employees"

You: "What is the schema of the customers table?"

AI: "The customers table has the following schema:

• id (integer, primary key)
• name (text)
• email (text)
• registration_date (date)
• last_purchase (date)
• total_spent (numeric)"

You: "How many customers made a purchase in the last month?"

AI: "Let me run a query to find out... Based on the data, 128 customers made a purchase in the last month. The total value of these purchases was $25,437.82."

Available Tools

MCP Database Utilities provides several tools your AI can use:

• dbutils-list-tables: List all tables in a database
• dbutils-run-query: Execute an SQL query (SELECT only)
• dbutils-get-stats: Get statistics about a table
• dbutils-list-constraints: List table constraints
• dbutils-explain-query: Get the query execution plan
• dbutils-get-performance: Get database performance metrics
• dbutils-analyze-query: Analyze a query for optimization

Need More Help?

• Technical Documentation - For developers and advanced users
• GitHub Issues - Report bugs or request features
• Smithery - Simplify installation and updates

Star History

License

This project is licensed under the MIT License - see the LICENSE file for details.