Encrypted SQLite MCP Server

MCP server for encrypted SQLite databases

A Model Context Protocol (MCP) server for working with encrypted SQLite databases using SQLCipher. This server provides tools to read database structures, query tables, and perform CRUD operations on encrypted SQLite databases.

Compatible with all MCP clients (Cursor, Claude Desktop, and others).

Works with encrypted databases from: MoneyMoney, 1Password, Signal, WhatsApp, Firefox, Telegram, KeePass, and other applications using SQLCipher encryption.

Features

• Encrypted SQLite Support: Works with SQLCipher 4 encrypted databases - the key differentiator of this MCP server
• Encrypted Passphrases: Support for AES-256-GCM encrypted passphrases with macOS Keychain integration
• Database Exploration: List tables, columns, indexes, and schema metadata
• Query Support: Execute arbitrary SQL queries (SELECT, INSERT, UPDATE, DELETE, DDL)
• CRUD Operations: Insert, update, and delete rows with filtering
• Configurable Cipher Profiles: Support for different SQLCipher configurations
• MCP Protocol: Full Model Context Protocol implementation via STDIO
• Security: SQL identifier validation to prevent SQL injection
• Debug Mode: Optional debug output via MCP_DEBUG environment variable
• Input Validation: Comprehensive validation for limits, offsets, and identifiers

Why Encrypted SQLite?

Many popular applications use encrypted SQLite databases (SQLCipher) to protect sensitive data. This MCP server is specifically designed to work with these encrypted databases.

Applications Using Encrypted SQLite Databases

• MoneyMoney (macOS): Financial management app with encrypted local databases
• 1Password: Password manager using SQLCipher for local vault storage
• Signal: Encrypted messaging app with SQLCipher-protected message databases
• WhatsApp: Messaging app using encrypted SQLite for local message storage
• Firefox: Browser using SQLCipher for encrypted login databases
• Telegram: Messaging app with encrypted local database storage
• KeePass: Password manager supporting encrypted SQLite database files

If you need to access data from any of these applications or other SQLCipher-encrypted databases, this MCP server provides the tools you need. Note that you need the passphrase of the encrypted database.

Requirements

• Java 21 or higher (JDK)
• Gradle (wrapper included)
• SQLite JDBC driver with encryption support (sqlite-jdbc-3.50.1.0.jar from sqlite-jdbc-crypt)

Quick Start

Cursor (One-Click Installation)

The easiest way to install this MCP server in Cursor is via the Cursor MCP Store:

1. Visit cursor.store/mcp/rosch100/mcp-encrypted-sqlite
2. Click "Add to Cursor"
3. Follow the prompts to configure your database path and passphrase

Other MCP Clients

This server works with any MCP-compatible client. See the Configuration section below for setup instructions.

Installation

Docker (Recommended)

Use the pre-built Docker image from GitHub Container Registry:

docker pull ghcr.io/rosch100/mcp-encrypted-sqlite:latest

Quick Start: See DOCKER_QUICKSTART.md for Docker Desktop setup.

Detailed Configuration: See DOCKER_CONFIGURATION.md for advanced options.

From Source

1. Clone the repository:

   git clone https://github.com/rosch100/mcp-encrypted-sqlite.git

   cd mcp-encrypted-sqlite

2. Build the project:

   ./gradlew build installDist

The build process will automatically download sqlite-jdbc-3.50.1.0.jar from sqlite-jdbc-crypt releases and place it in the libs/ directory.

The executable will be available at build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite.

Configuration

This MCP server works with any MCP-compatible client (Cursor, Claude Desktop, etc.). The configuration format follows the Model Context Protocol specification.

The server communicates via STDIO (standard input/output). Add the following configuration to your MCP client's configuration file:

Configuration file locations:

• Cursor: ~/.cursor/mcp.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Other clients: Refer to your client's documentation

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ]
    }
  }
}

Optional Parameters:

• transport: Defaults to "stdio" (can be omitted)
• cwd: Not needed when using absolute paths (can be omitted)
• immutable: Optional boolean in the --args JSON. When true, opens the DB with SQLite URI file:…?immutable=1 (no file locks). Use for peeking at DBs locked exclusively by another app (e.g. MoneyMoney). All write tools/SQL are disabled in this mode (insert_or_update / delete_rows omitted; execute_sql accepts read-only statements only).
• env: Only needed if Java is not in your system PATH or for custom Java installation:

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ],
      "env": {
        "JAVA_HOME": "/path/to/java/home"
      }
    }
  }
}

Docker Configuration

Plain Passphrase

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/database.sqlite:/data/database.sqlite:ro",
        "ghcr.io/rosch100/mcp-encrypted-sqlite:latest",
        "--args",
        "{\"db_path\":\"/data/database.sqlite\",\"passphrase\":\"your-passphrase\"}"
      ]
    }
  }
}

Encrypted Passphrase (Recommended)

When using encrypted passphrases, you must pass the encryption key as an environment variable:

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_SQLITE_ENCRYPTION_KEY=your-encryption-key",
        "-v", "/path/to/your/database.sqlite:/data/database.sqlite:ro",
        "ghcr.io/rosch100/mcp-encrypted-sqlite:latest",
        "--args",
        "{\"db_path\":\"/data/database.sqlite\",\"passphrase\":\"encrypted:your-encrypted-passphrase\"}"
      ]
    }
  }
}

Important Notes:

• The -e flag must come before the -v flag
• macOS Keychain is NOT accessible from Docker containers - pass the encryption key explicitly
• Get your encryption key: security find-generic-password -s "mcp-encrypted-sqlite" -a "encryption-key" -w
• The database file is mounted as read-only (:ro) by default. Remove :ro if you need write access

Security Warning: Storing both the encryption key and encrypted passphrase as plain text in your configuration file is a security risk. See DOCKER_CONFIGURATION.md for secure alternatives.

Custom Cipher Profile

Override the default SQLCipher 4 settings by including a cipherProfile in the configuration JSON:

{
  "mcpServers": {
    "encrypted-sqlite": {
      "command": "/path/to/mcp-encrypted-sqlite/build/install/mcp-encrypted-sqlite/bin/mcp-encrypted-sqlite",
      "args": [
        "--args",
        "{\"db_path\":\"/path/to/your/database.sqlite\",\"passphrase\":\"your-passphrase\",\"cipherProfile\":{\"name\":\"SQLCipher 4 defaults\",\"pageSize\":4096,\"kdfIterations\":256000,\"hmacAlgorithm\":\"HMAC_SHA512\",\"kdfAlgorithm\":\"PBKDF2_HMAC_SHA512\"}}"
      ]
    }
  }
}

Note: All fields in cipherProfile are optional - only specify the ones you want to override from the defaults. You can also specify cipherProfile in individual tool calls, but it's recommended to configure it once in the MCP server configuration for consistency.

Encrypted Passphrases

For enhanced security, you can store passphrases in encrypted form. The server uses AES-256-GCM encryption, which provides authenticated encryption and is both secure and fast.

macOS Keychain (Recommended for macOS)

1. Generate and store key in Keychain: Run: ./store-key-in-keychain.sh --generate

2. Encrypt your passphrase: Run: ./encrypt-passphrase.sh "your-plain-passphrase"

The key is automatically loaded from the Keychain when no environment variable is set.

Benefits:

• Key is securely encrypted and stored by macOS
• No environment variables needed
• Automatic unlock with macOS user password
• Works system-wide for all applications

Environment Variable (Cross-Platform)

1. Generate an encryption key: Run: java -cp build/libs/mcp-encrypted-sqlite-VERSION.jar com.example.mcp.sqlite.config.PassphraseEncryption

2. Set the encryption key: Run: export MCP_SQLITE_ENCRYPTION_KEY="<your-generated-key>"

3. Encrypt your passphrase: Run: java -cp build/libs/mcp-encrypted-sqlite-VERSION.jar com.example.mcp.sqlite.util.EncryptPassphrase "your-plain-passphrase"

Usage

Use the encrypted passphrase (with encrypted: prefix) in your configuration: