# MCPDB - Database Access MCP Server

MCPDB is a Laravel-based MCP (Model Context Protocol) server that provides Claude Desktop with secure access to multiple database connections. Through a web-based management interface, you can configure database connections and then query them directly from Claude Desktop using natural language.

## Features

- **Multi-Database Support**: Connect to MySQL, PostgreSQL, SQLite, and SQL Server databases
- **Web Management Interface**: Easy-to-use web UI for managing database connections
- **MCP Integration**: Seamlessly integrates with Claude Desktop via the Model Context Protocol
- **Secure Connection Management**: Store and manage database credentials securely
- **SQL Query Execution**: Execute SQL queries directly from Claude Desktop conversations

## Prerequisites

- Docker and Docker Compose (for Laravel Sail)
- Node.js and npm (for frontend assets)
- Claude Desktop application

## Installation

### 1. Clone and Setup the Project

```bash
git clone <repository-url>
cd mcpdb
```

### 2. Start the Laravel Application

```bash
# Copy environment file
cp .env.example .env

# Start Docker containers
./vendor/bin/sail up -d

# Install PHP dependencies
./vendor/bin/sail composer install

# Install Node.js dependencies and build assets
./vendor/bin/sail npm install
./vendor/bin/sail npm run dev

# Run database migrations
./vendor/bin/sail artisan migrate
```

The application will be available at http://localhost:8000

### 3. Configure Database Connections

1. Open http://localhost:8000 in your browser
2. Click "Add Connection" to create database connections
3. Fill in the connection details:
   - **Connection Name**: Unique identifier (e.g., "my_production_db")
   - **Driver**: mysql, pgsql, sqlite, or sqlsrv
   - **Host**: Database host address
   - **Port**: Database port (optional, uses default if empty)
   - **Database**: Database name
   - **Username**: Database username
   - **Password**: Database password
   - **Description**: Optional description
4. Test the connection to ensure it works
5. Make sure "Active" is checked

### 4. Configure Claude Desktop

Create or edit the Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the following configuration:

```json
{
  "mcpServers": {
    "mcpdb": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}
```

### 5. Install mcp-remote (if not already installed)

```bash
npm install -g mcp-remote
```

### 6. Restart Claude Desktop

Completely quit and restart Claude Desktop for the configuration to take effect.

## Usage

Once configured, you can interact with your databases directly through Claude Desktop:

### List Available Connections

```
What database connections are available?
```

### Execute SQL Queries

```
Execute this SQL query on the "my_production_db" connection: SELECT * FROM users LIMIT 5
```

```
Show me the table structure for the products table in the inventory database
```

```
Count the number of orders in the last 30 days using the sales_db connection
```

## Available MCP Tools

The server provides two main tools:

1. **list_connections**: Lists all active database connections
2. **execute_sql**: Executes SQL queries on specified connections

## Development

### Project Structure

- `app/Models/SubjectConnection.php` - Database connection model
- `app/Http/Controllers/ConnectionController.php` - Web interface for managing connections
- `app/Http/Controllers/McpController.php` - MCP server implementation
- `resources/views/connections/` - Web interface views
- `database/migrations/` - Database schema migrations

### Running Tests

```bash
./vendor/bin/sail artisan test
```

### Code Formatting

```bash
./vendor/bin/sail artisan pint
```

## Security Considerations

- Database passwords are stored in the application database
- Only active connections are exposed to the MCP server
- SQL queries are executed with the permissions of the configured database user
- Consider using read-only database users for security
- The MCP server runs on localhost only by default

## Troubleshooting

### MCP Server Not Connecting

1. Ensure Laravel server is running: `./vendor/bin/sail up -d`
2. Check MCP server health: `curl http://localhost:8000/health`
3. Verify Claude Desktop configuration file syntax
4. Check Claude Desktop logs: `~/Library/Logs/Claude/`

### Database Connection Failures

1. Test connections in the web interface: http://localhost:8000
2. Verify database credentials and network access
3. Check if database user has appropriate permissions
4. For remote databases, ensure firewall allows connections

### Asset Loading Issues

```bash
# Rebuild frontend assets
./vendor/bin/sail npm run dev
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and ensure code formatting
5. Submit a pull request

## License

This project is open-sourced software licensed under the MIT license.