Custom MCP Database Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Model Context Protocol (MCP) Server that provides a secure middleware layer for AI agents to execute database queries. It supports PostgreSQL, MySQL, MongoDB, and Oracle databases using an alias-based configuration system stored in SQLite. ## Commands ### Development ```bash make install # Install dependencies in virtual environment make run # Start the MCP server (runs ./venv/bin/python main.py) ``` ### CLI Database Management (Global Command) ```bash # Global command available from anywhere (recommended) mcp-db --help # Show all available commands with examples # Add database connection mcp-db add-db --alias <name> --type <postgres|mysql|mongo|oracle> --host <host> --port <port> --user <user> --password <password> --dbname <dbname> [--uri <mongo_uri>] # Remove database connection mcp-db remove-db --alias <name> # List all configured databases mcp-db list-aliases # Execute query (MongoDB queries automatically convert ObjectId strings) mcp-db execute-query --database_alias <alias> --query <query> [--params '{"key": "value"}'] [--collection <name>] [--oracle_schema <schema>] # List MongoDB collections mcp-db list-collections --database_alias <alias> ``` ### CLI Database Management (Local Command) ```bash # Alternative: Local command (requires being in project directory) python main.py add-db --alias <name> --type <postgres|mysql|mongo|oracle> --host <host> --port <port> --user <user> --password <password> --dbname <dbname> [--uri <mongo_uri>] python main.py remove-db --alias <name> python main.py list-aliases python main.py execute-query --database_alias <alias> --query <query> [--params '{"key": "value"}'] [--collection <name>] [--oracle_schema <schema>] python main.py list-collections --database_alias <alias> ``` ## Architecture ### Core Components - `main.py:1-629` - Main application with MCP server implementation and CLI interface - MCP server setup: `main.py:567-629` - CLI commands: `main.py:398-565` - Database query execution: `main.py:136-395` - `config_db.py:1-107` - SQLite-based configuration management for database connections - Connection storage: `config_db.py:19-65` - Connection retrieval: `config_db.py:67-107` ### Key Design Patterns 1. **Dual Mode Operation**: Single entry point serves as both MCP server and CLI tool 2. **Configuration Storage**: SQLite database (`mcp_config.sqlite3`) stores encrypted connection details 3. **Unified Query Interface**: Common `execute_query` method handles all database types 4. **Tool-based Architecture**: MCP tools expose database operations to AI agents ### Database Support - **SQL Databases** (PostgreSQL, MySQL, Oracle): Standard SQL with parameterized queries - **MongoDB**: JSON-based queries with collection specification - **Oracle**: Additional schema switching capability ## MCP Tools Exposed 1. `list_aliases()` - Returns all configured database aliases 2. `add_database(...)` - Adds new database connection 3. `remove_database(...)` - Removes database connection 4. `execute_query(...)` - Executes queries with proper parameterization 5. `list_collections(...)` - Lists MongoDB collections ## Important Notes - Database credentials are stored in `mcp_config.sqlite3` (gitignored) - Global command `mcp-db` is available from anywhere after installation - MongoDB queries automatically convert 24-character strings to ObjectId objects - All queries are limited to 10 results by default to prevent large outputs - Virtual environment must be activated or use full path to Python executable - MongoDB requires either connection URI or standard connection parameters - Oracle queries support schema switching via the `schema` parameter - All SQL queries support parameterized queries to prevent SQL injection