SimpleDB MCP

A Model Context Protocol (MCP) server for securely accessing and exploring relational databases. Built in Go with cross-platform credential management and biometric authentication.

Features

• Database Support: MySQL, PostgreSQL, Salesforce, and AWS Glue with connection pooling
• Secure Credentials: Cross-platform keychain/credential manager integration
• Biometric Auth: TouchID/FaceID on macOS, Windows Hello on Windows
• Connection Keep-Alive: Background monitoring keeps database connections healthy
• Read-Only Operations: Safe database exploration without modification risks
• MCP Compatible: Works with Claude Desktop, Cursor, Claude CLI, and other MCP clients

Supported Tools

Database Exploration

• list_connections - Show configured database connections
• list_databases - List databases on a connection
• list_schemas - List schemas (PostgreSQL only)
• list_tables - List tables in a database/schema
• describe_table - Show table structure and columns
• list_indexes - Show table indexes
• get_table_sample - Get sample rows from a table

Connection Monitoring

• get_connection_status - Get connection pool status and health information
• get_pool_metrics - Get overall connection pool metrics and statistics

Installation

Quick Install (macOS)

git clone https://github.com/eliziario/simpledb-mcp
cd simpledb-mcp
make install-macos

Quick Install (Windows)

git clone https://github.com/eliziario/simpledb-mcp
cd simpledb-mcp
# Run as Administrator
.\scripts\install-windows.ps1

Manual Build

git clone https://github.com/eliziario/simpledb-mcp
cd simpledb-mcp
make build-local  # or: make build-all for cross-platform

Configuration

The installation scripts automatically set up configuration directories and copy example files. To configure manually:

1. Run the configuration tool:

   simpledb-cli config  # Interactive TUI
   

2. Or edit configuration file directly:

   # Configuration is stored in:
   # macOS/Linux: ~/.config/simpledb-mcp/config.yaml
   # Windows: %USERPROFILE%\.config\simpledb-mcp\config.yaml
   

Usage

As MCP Server

The server runs as an MCP provider using stdio transport:

./bin/simpledb-mcp

With Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "simpledb": {
      "command": "/path/to/simpledb-mcp",
      "args": []
    }
  }
}

With Desktop Applications

SimpleDB MCP includes a stdio-to-HTTP proxy for desktop application compatibility while keeping the advantages of a long-running HTTP server.

Add to your desktop application configuration:

{
  "mcpServers": {
    "simpledb": {
      "command": "simpledb-mcp-proxy",
      "args": ["--server", "http://localhost:48384/mcp"]
    }
  }
}

The proxy automatically forwards stdio requests from desktop applications to your running SimpleDB MCP HTTP server. See Desktop Integration Guide for detailed setup instructions.

With Claude CLI

Register as an MCP provider:

claude-mcp add simpledb /path/to/simpledb-mcp

Configuration Format

connections:
  my-mysql:
    type: mysql
    host: localhost
    port: 3306
    database: myapp
    username: dbuser
  
  my-postgres:
    type: postgres
    host: db.example.com
    port: 5432
    database: analytics
    ssl_mode: require
    username: readonly
  
  my-salesforce:
    type: salesforce
    host: https://mycompany.my.salesforce.com
    # Credentials stored separately in keychain
  
  my-glue:
    type: glue
    host: us-east-1  # AWS region
    role_arn: arn:aws:iam::123456789012:role/AdminRole
    mfa_serial: arn:aws:iam::123456789012:mfa/your.username
    athena_s3_output: s3://your-athena-results-bucket/results/

settings:
  query_timeout: 30s      # Query timeout
  max_rows: 1000          # Max rows per query
  cache_credentials: 5m   # Credential cache duration
  require_biometric: true # Require biometric auth
  
  # Connection pool settings for keeping database connections alive
  connection_pool:
    enable_keepalive: true      # Enable background connection monitoring
    ping_interval: 30s          # How often to ping connections to keep them alive
    max_idle_time: 15m          # Maximum time a connection can be idle before cleanup
    max_error_count: 3          # Maximum consecutive errors before closing connection
    reconnect_delay: 5s         # Delay before attempting to reconnect after error

Salesforce Integration

SimpleDB MCP provides secure access to Salesforce objects through SOQL queries:

Salesforce Setup

1. Store Salesforce credentials:

   go run store_sf_creds.go my-salesforce https://mycompany.my.salesforce.com user@company.com password security_token
   

2. Get your Security Token:

   • Log into Salesforce → Settings → My Personal Information → Reset My Security Token
   • The token will be emailed to you

3. Salesforce Tools:

   • list_tables - Lists all queryable Salesforce objects (standard and custom)
   • describe_table - Shows object fields, types, and metadata
   • get_table_sample - Retrieves sample records using SOQL
   • list_databases/list_schemas - Return placeholder values for MCP client compatibility

Salesforce Features

• Read-Only Access: Uses SOQL SELECT queries only
• Field Filtering: Automatically limits to 20 most relevant fields for performance
• Type Mapping: Converts Salesforce field types to standard SQL equivalents
• Error Handling: Graceful handling of complex field types (address, location)

AWS Glue Integration

SimpleDB MCP provides secure access to AWS Glue Data Catalog and Athena for table sampling:

AWS Glue Setup

1. Configure AWS MFA authentication (choose one option):

   Option A: Native macOS Dialog (Recommended)

   • Set use_gauth: false or omit this field in your connection config
   • Enter MFA codes manually from your authenticator app via native dialog

   Option B: Automated with gauth

   • Set use_gauth: true in your connection config

   • Ensure you have the aws_mfa script configured in ~/.config/.aws_menu.ini

   • Install and configure gauth for automated MFA token generation

   • Your IAM user must have permission to assume the specified role

2. Required AWS Permissions:

   • glue:GetDatabases, glue:GetTables, glue:GetTable for catalog access
   • athena:StartQueryExecution, athena:GetQueryExecution, athena:GetQueryResults for sampling
   • s3:GetBucketLocation, s3:GetObject, s3:ListBucket, s3:PutObject for Athena results

3. Athena S3 Output Configuration: Set the S3 location for Athena query results in your connection config:

   my-glue:
     type: glue
     athena_s3_output: s3://your-athena-results-bucket/results/
   

   Alternatively, you can use the environment variable:

   export AWS_ATHENA_S3_OUTPUT="s3://your-athena-results-bucket/results/"
   

4. AWS Glue Tools:

   • list_databases - Lists all Glue Catalog databases
   • list_tables - Lists tables in a Glue database
   • describe_table - Shows table schema from Glue Catalog
   • get_table_sample - Executes Athena queries to sample table data
   • list_schemas - Returns database name (Glue uses database-level organization)

AWS Glue Features

• Flexible MFA Authentication:
  • Native macOS dialog for manual MFA code entry (default)
  • Automated gauth integration for power users
• Auto-refresh: STS credentials automatically refresh when expired
• Athena Integration: Table sampling uses Athena for actual data queries
• Pagination: Handles large numbers of databases/tables efficiently
• Timeout Protection: Configurable query timeouts prevent long-running queries

Security

• Credentials are stored in OS keychain/credential manager
• Biometric authentication required for credential access
• Read-only operations only - no data modification possible
• Query timeouts and row limits prevent resource abuse

Development

Project Structure

simpledb-mcp/
├── cmd/
│   ├── simpledb-mcp/      # Main server binary
│   └── simpledb-cli/      # Configuration CLI (planned)
├── internal/
│   ├── config/            # Configuration management
│   ├── credentials/       # Cross-platform credential store
│   ├── database/          # Database connections and queries
│   └── tools/             # MCP tool implementations
└── pkg/api/               # Server API

Adding Database Support

1. Add driver import to internal/database/database.go
2. Implement database-specific methods in new file (e.g., oracle.go)
3. Add type support in configuration and tools

License

MIT License - see LICENSE file for details.