sqlcipher-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,282 @@
+# SQLCipher MCP Server
+
+An MCP (Model Context Protocol) server that provides read-only access to SQLCipher-encrypted SQLite databases. This server allows you to query encrypted SQLite databases using SQLCipher 3 default encryption settings.
+
+## Overview
+
+This MCP server enables you to:
+- Connect to SQLCipher-encrypted SQLite databases
+- Execute SELECT queries (read-only mode)
+- Retrieve query results in a structured format
+- Use SQLCipher 3 default encryption settings
+
+## Prerequisites
+
+- Node.js (v18 or higher)
+- npm or yarn package manager
+- Access to a SQLCipher-encrypted SQLite database file
+- Database password (will be provided via environment variable)
+
+## Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g sqlcipher-mcp-server
+```
+
+Or install locally in your project:
+
+```bash
+npm install sqlcipher-mcp-server
+```
+
+### Option 2: Install from source
+
+1. Clone or download this repository
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+## Configuration
+
+### Environment Variable
+
+Set the `SQLCIPHER_PASSWORD` environment variable with your database password:
+
+**Windows (PowerShell):**
+```powershell
+$env:SQLCIPHER_PASSWORD = "your_database_password"
+```
+
+**Windows (Command Prompt):**
+```cmd
+set SQLCIPHER_PASSWORD=your_database_password
+```
+
+**Linux/macOS:**
+```bash
+export SQLCIPHER_PASSWORD="your_database_password"
+```
+
+**Permanent setup (recommended):**
+- Add the environment variable to your system settings
+- Or use a `.env` file with a tool like `dotenv` (requires additional setup)
+
+## Usage
+
+### Starting the Server
+
+The MCP server communicates via stdio (standard input/output). Start it with:
+
+```bash
+npm start
+```
+
+Or directly:
+
+```bash
+node index.js
+```
+
+### MCP Client Configuration
+
+#### For Cursor IDE
+
+1. **Install the package globally:**
+   ```bash
+   npm install -g sqlcipher-mcp-server
+   ```
+
+2. **Find the global installation path:**
+   ```bash
+   npm root -g
+   ```
+
+3. **Configure Cursor IDE:**
+   
+   Open Cursor's MCP settings file (location varies by OS):
+   - **Windows**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+   - **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+   - **Linux**: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+   Add this configuration:
+   ```json
+   {
+     "mcpServers": {
+       "sqlcipher": {
+         "command": "node",
+         "args": ["C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\node_modules\\sqlcipher-mcp-server\\index.js"],
+         "env": {
+           "SQLCIPHER_PASSWORD": "your_database_password"
+         }
+       }
+     }
+   }
+   ```
+   
+   **Note:** Replace the path with your actual global npm path from step 2.
+
+4. **Restart Cursor IDE** for changes to take effect.
+
+#### Alternative: Using npx (no global installation)
+
+```json
+{
+  "mcpServers": {
+    "sqlcipher": {
+      "command": "npx",
+      "args": ["-y", "sqlcipher-mcp-server"],
+      "env": {
+        "SQLCIPHER_PASSWORD": "your_database_password"
+      }
+    }
+  }
+}
+```
+
+#### For other MCP clients
+
+Configure your MCP client to use this server:
+
+```json
+{
+  "mcpServers": {
+    "sqlcipher": {
+      "command": "node",
+      "args": ["path/to/sqlcipher-mcp-server/index.js"],
+      "env": {
+        "SQLCIPHER_PASSWORD": "your_database_password"
+      }
+    }
+  }
+}
+```
+
+For detailed integration instructions, see [PUBLISHING.md](./PUBLISHING.md).
+
+### Available Tools
+
+#### `execute_query`
+
+Execute a SELECT query on a SQLCipher-encrypted database.
+
+**Parameters:**
+- `database_path` (string, required): Full path to the SQLCipher database file
+- `query` (string, required): SQL SELECT query to execute
+
+**Returns:**
+- Formatted text output with query results
+- JSON representation of results including:
+  - `columns`: Array of column names
+  - `rows`: Array of row objects
+  - `rowCount`: Number of rows returned
+
+**Example Usage:**
+
+```javascript
+// Example 1: Simple SELECT query
+{
+  "tool": "execute_query",
+  "arguments": {
+    "database_path": "C:\\Users\\Username\\AppData\\Local\\AppName\\database.db",
+    "query": "SELECT * FROM users LIMIT 10"
+  }
+}
+
+// Example 2: SELECT with WHERE clause
+{
+  "tool": "execute_query",
+  "arguments": {
+    "database_path": "C:\\Users\\Username\\AppData\\Local\\AppName\\database.db",
+    "query": "SELECT id, name, email FROM users WHERE active = 1"
+  }
+}
+
+// Example 3: SELECT with JOIN
+{
+  "tool": "execute_query",
+  "arguments": {
+    "database_path": "C:\\Users\\Username\\AppData\\Local\\AppName\\database.db",
+    "query": "SELECT u.name, o.order_id FROM users u JOIN orders o ON u.id = o.user_id"
+  }
+}
+```
+
+## Security Features
+
+- **Read-Only Mode**: Only SELECT queries are allowed. INSERT, UPDATE, DELETE, and other modifying operations are blocked.
+- **Password Protection**: Database password is read from environment variable and never exposed in logs or error messages.
+- **Query Validation**: All queries are validated to ensure they are SELECT queries only.
+- **Error Handling**: Sensitive information is not exposed in error messages.
+
+## Error Handling
+
+The server handles various error scenarios:
+
+- **Database file not found**: Returns clear error message
+- **Invalid password**: Returns generic error (doesn't expose password details)
+- **SQL syntax errors**: Returns specific syntax error messages
+- **Table/column not found**: Returns specific error messages
+- **Non-SELECT queries**: Returns error explaining read-only restriction
+
+## Database Location
+
+The database file path should be provided each time you execute a query. Common locations for Windows applications:
+
+- `C:\Users\<Username>\AppData\Local\<AppName>\database.db`
+- `C:\Users\<Username>\AppData\Roaming\<AppName>\database.db`
+- `C:\ProgramData\<AppName>\database.db`
+
+## Limitations
+
+- **Read-Only**: Only SELECT queries are supported
+- **Single Connection**: Each query opens and closes a new database connection
+- **Result Size**: Results are limited to 1000 rows for display (full results available in JSON)
+- **SQLCipher 3 Only**: Uses SQLCipher 3 default encryption settings
+
+## Troubleshooting
+
+### "Database password not found" Error
+- Ensure `SQLCIPHER_PASSWORD` environment variable is set
+- Restart your MCP client after setting the environment variable
+- Check that the environment variable is available to the Node.js process
+
+### "Database file not found" Error
+- Verify the database path is correct
+- Use absolute paths instead of relative paths
+- Check file permissions
+
+### "Invalid password" Error
+- Verify the password matches the one used to encrypt the database
+- Ensure SQLCipher 3 defaults are used (as this server expects)
+- Check for extra spaces or special characters in the password
+
+### Connection Issues
+- Ensure the database file is not locked by another application
+- Verify the database file is a valid SQLCipher database
+- Check that SQLCipher 3 encryption was used (not SQLCipher 4)
+
+## Development
+
+### Project Structure
+
+```
+MyMCP/
+├── index.js              # Main MCP server entry point
+├── lib/
+│   └── database.js       # Database connection and query logic
+├── package.json          # Project dependencies
+└── README.md             # This file
+```
+
+### Dependencies
+
+- `@modelcontextprotocol/sdk`: MCP SDK for Node.js
+- `@journeyapps/sqlcipher`: SQLCipher bindings for Node.js
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { connectDatabase, executeQuery, closeConnection } from './lib/database.js';
+
+/**
+ * SQLCipher MCP Server
+ * Provides read-only access to SQLCipher-encrypted SQLite databases
+ */
+
+// Get database password from environment variable
+const DB_PASSWORD = process.env.SQLCIPHER_PASSWORD;
+
+// Create MCP server instance
+const server = new Server(
+    {
+        name: 'sqlcipher-mcp-server',
+        version: '1.0.0',
+    },
+    {
+        capabilities: {
+            tools: {},
+        },
+    }
+);
+
+/**
+ * List available tools
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'execute_query',
+                description: 'Execute a SELECT query on a SQLCipher-encrypted SQLite database. Only read-only queries are allowed.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        database_path: {
+                            type: 'string',
+                            description: 'Path to the SQLCipher database file',
+                        },
+                        query: {
+                            type: 'string',
+                            description: 'SQL SELECT query to execute (read-only)',
+                        },
+                    },
+                    required: ['database_path', 'query'],
+                },
+            },
+        ],
+    };
+});
+
+/**
+ * Handle tool execution requests
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    if (name === 'execute_query') {
+        try {
+            // Validate required parameters
+            if (!args || typeof args !== 'object') {
+                throw new Error('Invalid arguments: arguments must be an object');
+            }
+
+            const { database_path, query } = args;
+
+            // Validate database_path
+            if (!database_path || typeof database_path !== 'string') {
+                throw new Error('database_path is required and must be a string');
+            }
+
+            // Validate query
+            if (!query || typeof query !== 'string') {
+                throw new Error('query is required and must be a string');
+            }
+
+            // Connect to database (password is optional - will work with unencrypted databases)
+            let db = null;
+            try {
+                db = await connectDatabase(database_path, DB_PASSWORD);
+            } catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Failed to connect to database: ${error.message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+
+            // Execute query
+            try {
+                const result = executeQuery(db, query);
+
+                // Format results for response
+                const responseText = formatQueryResults(result);
+
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                };
+            } catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Query execution failed: ${error.message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            } finally {
+                // Always close the database connection
+                closeConnection(db);
+            }
+        } catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    } else {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Unknown tool: ${name}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+
+/**
+ * Format query results as a readable string
+ * 
+ * @param {Object} result - Query result object with columns, rows, and rowCount
+ * @returns {string} Formatted result string
+ */
+function formatQueryResults(result) {
+    const { columns, rows, rowCount } = result;
+
+    if (rowCount === 0) {
+        return `Query executed successfully. No rows returned.\nColumns: ${columns.join(', ')}`;
+    }
+
+    // Build table-like output
+    let output = `Query executed successfully. ${rowCount} row(s) returned.\n\n`;
+
+    // Add column headers
+    output += `Columns: ${columns.join(' | ')}\n`;
+    output += '-'.repeat(columns.join(' | ').length) + '\n';
+
+    // Add rows (limit to first 1000 rows for display)
+    const displayRows = rows.slice(0, 1000);
+    for (const row of displayRows) {
+        const values = columns.map(col => {
+            const value = row[col];
+            // Handle null/undefined
+            if (value === null || value === undefined) {
+                return 'NULL';
+            }
+            // Convert to string and truncate long values
+            const str = String(value);
+            return str.length > 50 ? str.substring(0, 47) + '...' : str;
+        });
+        output += values.join(' | ') + '\n';
+    }
+
+    if (rows.length > 1000) {
+        output += `\n... (showing first 1000 of ${rowCount} rows)`;
+    }
+
+    // Add JSON representation for programmatic access
+    output += '\n\nJSON representation:\n';
+    output += JSON.stringify(result, null, 2);
+
+    return output;
+}
+
+/**
+ * Start the MCP server
+ */
+async function main() {
+    // Check if password is set (warn but don't fail - might be set later)
+    if (!DB_PASSWORD) {
+        console.error(
+            'Warning: SQLCIPHER_PASSWORD environment variable is not set. ' +
+            'Database connections will fail until this is configured.'
+        );
+    }
+
+    // Create stdio transport
+    const transport = new StdioServerTransport();
+
+    // Connect server to transport
+    await server.connect(transport);
+
+    console.error('SQLCipher MCP Server running on stdio');
+}
+
+// Start the server
+main().catch((error) => {
+    console.error('Fatal error starting server:', error);
+    process.exit(1);
+});

package/lib/database.js

@@ -0,0 +1,216 @@
+import sqlcipher from '@journeyapps/sqlcipher';
+import fs from 'fs';
+
+// Extract Database from the sqlcipher module object
+const Database = sqlcipher.Database;
+
+/**
+ * Connects to a SQLite database (encrypted or unencrypted)
+ * Supports both SQLCipher-encrypted and plain SQLite databases
+ * 
+ * @param {string} dbPath - Path to the database file
+ * @param {string} [password] - Optional database password (for encrypted databases)
+ * @returns {Promise<Database>} Database connection instance
+ * @throws {Error} If database file doesn't exist or connection fails
+ */
+export function connectDatabase(dbPath, password) {
+    return new Promise((resolve, reject) => {
+        // Validate database path exists
+        if (!fs.existsSync(dbPath)) {
+            return reject(new Error(`Database file not found: ${dbPath}`));
+        }
+
+        let db = null;
+        // Open database connection with callback
+        db = new Database(dbPath, (err) => {
+            if (err) {
+                return reject(new Error(`Failed to open database: ${err.message}`));
+            }
+
+            // If no password provided, treat as unencrypted SQLite database
+            if (!password || password.trim() === '') {
+                // Verify the database is accessible by running a simple query
+                db.get('SELECT 1', (getErr, row) => {
+                    if (getErr) {
+                        db.close((closeErr) => {
+                            // Ignore close errors
+                        });
+                        return reject(new Error(`Failed to verify database: ${getErr.message}`));
+                    }
+                    resolve(db);
+                });
+                return;
+            }
+
+            // Password provided - treat as encrypted SQLCipher database
+            // Explicitly set SQLCipher 3 compatibility mode
+            // This ensures SQLCipher 3 defaults are used:
+            // - Page size: 1024 bytes
+            // - PBKDF2 iterations: 64,000
+            // - KDF algorithm: PBKDF2-HMAC-SHA1
+            // - HMAC algorithm: HMAC-SHA1
+            db.exec('PRAGMA cipher_compatibility = 3', (compatErr) => {
+                if (compatErr) {
+                    db.close((closeErr) => {
+                        // Ignore close errors
+                    });
+                    return reject(new Error(`Failed to set SQLCipher 3 compatibility: ${compatErr.message}`));
+                }
+
+                // Set SQLCipher 3 default encryption settings
+                // PRAGMA key sets the encryption key using SQLCipher 3 defaults
+                // PRAGMA key does NOT support parameterized queries, so we must embed the password directly
+                // Escape single quotes in password for SQL (double them) and escape backslashes
+                const escapedPassword = password.replace(/\\/g, '\\\\').replace(/'/g, "''");
+                
+                // Use db.exec() with callback for PRAGMA key
+                db.exec(`PRAGMA key = '${escapedPassword}'`, (execErr) => {
+                    if (execErr) {
+                        db.close((closeErr) => {
+                            // Ignore close errors
+                        });
+                        return reject(new Error(`Failed to set encryption key: ${execErr.message}`));
+                    }
+                    
+                    // Verify the database is accessible by running a simple query
+                    // This will throw an error if the password is incorrect
+                    db.get('SELECT 1', (getErr, row) => {
+                        if (getErr) {
+                            db.close((closeErr) => {
+                                // Ignore close errors
+                            });
+
+                            if (getErr.message.includes('file is not a database') || 
+                                getErr.message.includes('malformed database') ||
+                                getErr.code === 'SQLITE_NOTADB') {
+                                return reject(new Error('Invalid password or database is corrupted'));
+                            }
+                            return reject(new Error(`Failed to verify database: ${getErr.message}`));
+                        }
+                        
+                        resolve(db);
+                    });
+                });
+            });
+        });
+    });
+}
+
+/**
+ * Validates that a SQL query is a SELECT query (read-only)
+ * 
+ * @param {string} query - SQL query string
+ * @returns {boolean} True if query is a SELECT query
+ * @throws {Error} If query is not a SELECT query
+ */
+function validateSelectQuery(query) {
+    if (!query || typeof query !== 'string') {
+        throw new Error('Query must be a non-empty string');
+    }
+
+    // Trim and normalize whitespace
+    const normalizedQuery = query.trim().replace(/\s+/g, ' ');
+
+    // Check if query starts with SELECT (case-insensitive)
+    if (!normalizedQuery.match(/^SELECT\s+/i)) {
+        throw new Error('Only SELECT queries are allowed (read-only mode)');
+    }
+
+    // Additional check: ensure no DDL or DML keywords are present
+    const forbiddenKeywords = [
+        'INSERT', 'UPDATE', 'DELETE', 'DROP', 'CREATE', 'ALTER', 
+        'TRUNCATE', 'REPLACE', 'PRAGMA'
+    ];
+    
+    const upperQuery = normalizedQuery.toUpperCase();
+    for (const keyword of forbiddenKeywords) {
+        // Check for keyword followed by space or semicolon (to avoid false positives)
+        const regex = new RegExp(`\\b${keyword}\\s+`, 'i');
+        if (regex.test(normalizedQuery) && keyword !== 'SELECT') {
+            throw new Error(`Query contains forbidden keyword: ${keyword}. Only SELECT queries are allowed.`);
+        }
+    }
+
+    return true;
+}
+
+/**
+ * Executes a SELECT query on the database and returns results
+ * 
+ * @param {Database} db - Database connection instance
+ * @param {string} query - SQL SELECT query to execute
+ * @returns {Promise<Object>} Query results with columns, rows, and rowCount
+ * @throws {Error} If query is invalid or execution fails
+ */
+export function executeQuery(db, query) {
+    return new Promise((resolve, reject) => {
+        // Validate query is a SELECT query
+        try {
+            validateSelectQuery(query);
+        } catch (validationError) {
+            return reject(validationError);
+        }
+
+        // Prepare and execute the query with callback
+        const statement = db.prepare(query, (prepareErr) => {
+            if (prepareErr) {
+                return reject(new Error(`Query preparation failed: ${prepareErr.message}`));
+            }
+            
+            // Execute query with callback - statement.all() requires a callback
+            statement.all((allErr, rows) => {
+                if (allErr) {
+                    statement.finalize();
+                    if (allErr.message.includes('no such table')) {
+                        return reject(new Error(`Table not found: ${allErr.message}`));
+                    } else if (allErr.message.includes('no such column')) {
+                        return reject(new Error(`Column not found: ${allErr.message}`));
+                    } else if (allErr.message.includes('syntax error')) {
+                        return reject(new Error(`SQL syntax error: ${allErr.message}`));
+                    }
+                    return reject(new Error(`Query execution failed: ${allErr.message}`));
+                }
+
+                // Get column names from the first row
+                let columns = [];
+                if (rows && rows.length > 0) {
+                    columns = Object.keys(rows[0]);
+                }
+
+                // Finalize the statement
+                statement.finalize();
+
+                resolve({
+                    columns: columns,
+                    rows: rows || [],
+                    rowCount: rows ? rows.length : 0
+                });
+            });
+        });
+    });
+}
+
+/**
+ * Closes a database connection
+ * Ensures all statements are finalized before closing
+ * 
+ * @param {Database} db - Database connection instance
+ */
+export function closeConnection(db) {
+    if (!db || typeof db.close !== 'function') {
+        return;
+    }
+
+    try {
+        // Close with callback to handle any errors gracefully
+        db.close((err) => {
+            if (err) {
+                // Log but don't throw - closing should be best effort
+                console.error('Error closing database connection:', err.message);
+            }
+        });
+    } catch (error) {
+        // Log but don't throw - closing should be best effort
+        console.error('Error closing database connection:', error.message);
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "sqlcipher-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server for querying SQLCipher-encrypted SQLite databases",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "sqlcipher-mcp-server": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "lib/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "start:http": "node server-http.js",
+    "test:http": "node server-http.js",
+    "dev": "nodemon index.js",
+    "dev:http": "nodemon server-http.js",
+    "prepublishOnly": "npm test || exit 0"
+  },
+  "keywords": [
+    "mcp",
+    "sqlcipher",
+    "sqlite",
+    "database",
+    "model-context-protocol",
+    "encrypted-database",
+    "cursor-ide"
+  ],
+  "author": "Sathira Guruge",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sathiraguruge/SQLLiteMCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sathiraguruge/SQLLiteMCP/issues"
+  },
+  "homepage": "https://github.com/sathiraguruge/SQLLiteMCP",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@journeyapps/sqlcipher": "^5.1.1",
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "express": "^4.22.1"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.11"
+  }
+}