MCP Database Server

This project provides a Middleware/Control Plane (MCP) server that allows code agents (like Gemini, Claude Desktop, and Claude Code) to securely execute queries against various databases (PostgreSQL, MySQL, MongoDB, Oracle) without directly exposing credentials. Database connection configurations are managed within an SQLite database (mcp_config.sqlite3).

1. Installation

To set up the project, follow these steps:

Clone the repository (if you haven't already):

git clone <repository_url>
cd custom-mcp-database

Install dependencies: This project uses a venv (virtual environment) to manage dependencies. Run the following command to create the virtual environment and install the required Python packages:
```
make install
```
This will create a venv/ directory and install everything listed in requirements.txt.

2. Running the MCP Server

To start the MCP server, use the make run command:

make run

The server will start and listen for incoming requests from your code agents.

3. Database Configuration

Database connections are stored in mcp_config.sqlite3. You can manage these connections using the global mcp-db command (recommended) or the local main.py script.

Adding a Database Connection

Use the add-db command. The required parameters vary by database type.

General Syntax (Global Command - Recommended):

mcp-db add-db --alias <alias> --type <type> [connection_parameters]

Alternative (Local Command):

python main.py add-db --alias <alias> --type <type> [connection_parameters]

Examples (Global Command):

PostgreSQL:

mcp-db add-db --alias pg_dev --type postgres --host localhost --port 5432 --user myuser --password mypassword --dbname mydb

MySQL:

mcp-db add-db --alias mysql_prod --type mysql --host 192.168.1.10 --port 3306 --user root --password secret --dbname production_db

Oracle:

mcp-db add-db --alias oracle_test --type oracle --host oracle.example.com --port 1521 --user system --password oraclepass --dbname ORCLPDB1

MongoDB:

mcp-db add-db --alias mongo_cluster --type mongo --uri "mongodb+srv://user:pass@cluster.mongodb.net/" --dbname myapp_db

Removing a Database Connection

Use the remove-db command with the alias of the connection you want to remove:

Global Command:

mcp-db remove-db --alias <alias>

Local Command:

python main.py remove-db --alias <alias>

Example:

mcp-db remove-db --alias pg_dev

Getting Help

For detailed help and examples:

mcp-db --help
mcp-db execute-query --help

4. Integration with Code Agents

Gemini

Once the MCP server is running (make run), Gemini will automatically discover and make the following tools available for interacting with your configured databases:

list_aliases(): Lists all configured database aliases.
add_database(...): Adds a new database connection.
remove_database(...): Removes a database connection.
execute_query(database_alias, query, params, schema): Executes a query against a configured database.

Gemini Usage Examples:

List aliases:
```
list_aliases()
```

Execute a SQL query (PostgreSQL/MySQL/Oracle):

execute_query(database_alias="pg_dev", query="SELECT * FROM users WHERE id = %s;", params={"id": 1})

Execute a MongoDB query:

execute_query(database_alias="mongo_cluster", query='''{"name": "John Doe"}''', params={"collection": "users"})

Claude Desktop

To integrate with Claude Desktop, you need to configure its claude_desktop_config.json file to point to your MCP server. Create or modify this file (usually located in your Claude Desktop configuration directory) with an entry similar to this:

{
  "mcpServers": {
    "Custom DB Server": {
      "command": "/your-path-to/custom-mcp-database/venv/bin/python",
      "args": [
        "/your-path-to/custom-mcp-database/main.py"
      ],
      "workingDirectory": "/your-path-to/custom-mcp-database"
    }
  }
}

Important: Replace /your-path-to/custom-mcp-database with the actual absolute path to your custom-mcp-database directory.

After configuring, restart Claude Desktop. The MCP tools will then be available for use within Claude Desktop.

Tool Configuration for AI Agents

To enable AI agents like Claude Code and Gemini to automatically discover and utilize the MCP server's tools, you need to configure them to launch or connect to the MCP server. This typically involves providing the path to the main.py script and specifying the working directory.

Here are examples of how you might configure your AI agent's mcpServers section:

For Claude Code

{
  "mcpServers": {
    "Custom DB Server": {
      "command": "/your-path-to/custom-mcp-database/venv/bin/python",
      "args": [
        "/your-path-to/custom-mcp-database/main.py"
      ],
      "workingDirectory": "/your-path-to/custom-mcp-database"
    }
  }
}

For Gemini

{
  "mcpServers": {
    "Custom DB Server": {
      "command": "/your-path-to/custom-mcp-database/venv/bin/python",
      "args": [
        "/your-path-to/custom-mcp-database/main.py"
      ],
      "workingDirectory": "/your-path-to/custom-mcp-database"
    }
  }
}