Installation and Configuration

Installation & Configuration

Last Updated: October 4, 2025 7:00 AM EST

Complete installation and configuration guide for the SQLite MCP Server across different environments and use cases.

---

🚀 Quick Installation

⚡ Install to Cursor IDE (Fastest)

Click the button below to install directly into Cursor:

Or copy this deep link and paste into your browser:

cursor://anysphere.cursor-deeplink/mcp/install?name=SQLite%20MCP%20Server&config=eyJzcWxpdGUtbWNwIjp7ImFyZ3MiOlsicnVuIiwiLWkiLCItLXJtIiwiLXYiLCIkKHB3ZCk6L3dvcmtzcGFjZSIsIndyaXRlbm90ZW5vdy9zcWxpdGUtbWNwLXNlcnZlcjpsYXRlc3QiLCItLWRiLXBhdGgiLCIvd29ya3NwYWNlL3NxbGl0ZV9tY3AuZGIiXSwiY29tbWFuZCI6ImRvY2tlciJ9fQ==

Requirements:

• ✅ Docker installed and running
• ✅ ~500MB disk space available

What happens:

1. Cursor prompts you to install the server
2. Automatically configures the Docker setup
3. Creates a ./sqlite_mcp.db file for your database
4. Restarts Cursor and connects to SQLite MCP

---

Docker (Recommended)

# Run instantly with Docker (creates a project-local database)
docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server:latest \
  --db-path /workspace/sqlite_mcp.db

🛡️ Supply Chain Security

For enhanced security and reproducible builds:

# Find available SHA tags at: https://hub.docker.com/r/writenotenow/sqlite-mcp-server/tags
# Look for tags starting with "master-" or "sha256-" for cryptographically verified builds

# Option 1: Human-readable timestamped builds (recommended)
docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server:master-YYYYMMDD-HHMMSS-<commit> \
  --db-path /workspace/sqlite_mcp.db

# Option 2: Multi-arch manifest digest (maximum security)
docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server@sha256:<manifest-digest> \
  --db-path /workspace/sqlite_mcp.db

How to Find SHA Tags:

1. Visit Docker Hub Tags
2. For convenience: Use master-YYYYMMDD-HHMMSS-<commit> tags (human-readable, multi-arch)
3. For maximum security: Use sha256-<hash> tags (manifest digests, immutable)

Understanding SHA Tags:

• 🏷️ master-YYYYMMDD-HHMMSS-<commit> - Human-readable, timestamped, multi-arch safe
• 🔒 sha256-<manifest-digest> - Multi-arch manifest digest (works on all architectures)
• ⚠️ Architecture-specific digests - Only for debugging specific architectures

Security Features:

• ✅ Build Provenance - Cryptographic proof of build process
• ✅ SBOM Available - Complete software bill of materials
• ✅ Supply Chain Attestations - Verifiable build integrity

Python Package

# Install from PyPI
pip install sqlite-mcp-server-enhanced

# Or install with uv (faster)
uv add sqlite-mcp-server-enhanced

From Source

# Clone and install
git clone https://github.com/neverinfamous/sqlite-mcp-server.git
cd sqlite-mcp-server
pip install -e .

---

🐳 Docker Installation

Basic Docker Usage

# Basic usage with local database
docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server:latest \
  --db-path /workspace/my_database.db

# Interactive mode with shell access
docker run -it --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server:latest \
  bash

Docker Compose Setup

# docker-compose.yml
version: '3.8'
services:
  sqlite-mcp:
    image: writenotenow/sqlite-mcp-server:latest
    volumes:
      - ./data:/workspace
      - ./backups:/backups
    environment:
      - SQLITE_DB_PATH=/workspace/app.db
      - MCP_SERVER_NAME=sqlite-mcp
    stdin_open: true
    tty: true

Persistent Data with Docker

# Create named volume for persistence
docker volume create sqlite_data

# Run with named volume
docker run -i --rm \
  -v sqlite_data:/data \
  writenotenow/sqlite-mcp-server:latest \
  --db-path /data/persistent.db

---

🐍 Python Installation

Virtual Environment Setup

# Create virtual environment
python -m venv sqlite-mcp-env
source sqlite-mcp-env/bin/activate  # Linux/Mac
# or
sqlite-mcp-env\Scripts\activate     # Windows

# Install package
pip install sqlite-mcp-server-enhanced

Using uv (Recommended)

# Install uv if not already installed
pip install uv

# Create project and install
uv init sqlite-mcp-project
cd sqlite-mcp-project
uv add sqlite-mcp-server-enhanced

# Run with uv
uv run python -m mcp_server_sqlite --db-path ./database.db

Development Installation

# Clone repository
git clone https://github.com/neverinfamous/sqlite-mcp-server.git
cd sqlite-mcp-server

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements-dev.txt

---

⚙️ Configuration Options

Command Line Arguments

# Basic configuration
python -m mcp_server_sqlite \
  --db-path ./my_database.db \
  --host localhost \
  --port 8080

# Advanced configuration
python -m mcp_server_sqlite \
  --db-path ./my_database.db \
  --host 0.0.0.0 \
  --port 8080 \
  --log-level INFO \
  --enable-wal \
  --cache-size 10000 \
  --timeout 30

Environment Variables

# Set environment variables
export SQLITE_DB_PATH="./my_database.db"
export MCP_SERVER_HOST="localhost"
export MCP_SERVER_PORT="8080"
export MCP_LOG_LEVEL="INFO"
export SQLITE_ENABLE_WAL="true"

# Run with environment variables
python -m mcp_server_sqlite

Configuration File

// mcp-config.json
{
  "mcpServers": {
    "sqlite-mcp": {
      "command": "python",
      "args": ["-m", "mcp_server_sqlite"],
      "env": {
        "SQLITE_DB_PATH": "./database.db",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

---

🔧 Advanced Configuration

Database Optimization Settings

# High-performance configuration
python -m mcp_server_sqlite \
  --db-path ./database.db \
  --enable-wal \
  --cache-size 50000 \
  --mmap-size 268435456 \
  --synchronous NORMAL \
  --journal-mode WAL

Security Configuration

# Security-focused configuration
python -m mcp_server_sqlite \
  --db-path ./database.db \
  --enable-foreign-keys \
  --secure-delete \
  --read-only false \
  --max-connections 10 \
  --timeout 30

Memory-Constrained Environment

# Low-memory configuration
python -m mcp_server_sqlite \
  --db-path ./database.db \
  --cache-size 2000 \
  --mmap-size 0 \
  --temp-store file \
  --synchronous FULL

---

🌐 Integration with MCP Clients

Claude Desktop Integration

// Add to Claude Desktop MCP configuration
{
  "mcpServers": {
    "sqlite-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspaceFolder}:/workspace",
        "writenotenow/sqlite-mcp-server:latest",
        "--db-path", "/workspace/claude_database.db"
      ]
    }
  }
}

Cursor Integration

// Add to Cursor MCP settings
{
  "mcpServers": {
    "sqlite-database": {
      "command": "python",
      "args": ["-m", "mcp_server_sqlite"],
      "env": {
        "SQLITE_DB_PATH": "./cursor_workspace.db"
      }
    }
  }
}

Custom MCP Client Integration

# Python MCP client example
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_client():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "mcp_server_sqlite"],
        env={"SQLITE_DB_PATH": "./client_database.db"}
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize connection
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in tools.tools]}")

---

🧪 Testing Installation

Quick Verification

# Test basic functionality
python -c "
import sqlite3
from mcp_server_sqlite import create_server
print('✅ Installation successful!')
print('✅ SQLite version:', sqlite3.sqlite_version)
"

Comprehensive Test Suite

# Run built-in test suite
python test_runner.py --quick

# Test specific features
python test_runner.py --json        # JSON helper tools
python test_runner.py --fts         # Full-text search
python test_runner.py --spatial     # Spatial features
python test_runner.py --standard    # Comprehensive test

Docker Test

# Test Docker installation
docker run --rm writenotenow/sqlite-mcp-server:latest \
  python -c "
from mcp_server_sqlite import create_server
print('✅ Docker installation successful!')
"

---

🔍 Troubleshooting

Common Issues

Import Errors

# If you get import errors
pip install --upgrade sqlite-mcp-server-enhanced
pip install --upgrade mcp

# Check Python version (requires 3.9+)
python --version

Database Permission Issues

# Fix database file permissions
chmod 666 ./database.db
chown $(whoami) ./database.db

# Or run with appropriate user in Docker
docker run -u $(id -u):$(id -g) -i --rm \
  -v $(pwd):/workspace \
  writenotenow/sqlite-mcp-server:latest

SQLite Version Issues

# Check SQLite capabilities
import sqlite3
print("SQLite version:", sqlite3.sqlite_version)
print("Available extensions:", sqlite3.version_info)

# Test JSON support
conn = sqlite3.connect(':memory:')
try:
    conn.execute("SELECT json('{\"test\": true}')")
    print("✅ JSON support available")
except:
    print("❌ JSON support not available")

Performance Issues

# Enable WAL mode for better performance
python -m mcp_server_sqlite \
  --db-path ./database.db \
  --enable-wal \
  --cache-size 20000

# Monitor performance
python -c "
import sqlite3
conn = sqlite3.connect('./database.db')
print('Cache size:', conn.execute('PRAGMA cache_size').fetchone())
print('Journal mode:', conn.execute('PRAGMA journal_mode').fetchone())
"

---

🚀 Production Deployment

Systemd Service (Linux)

# /etc/systemd/system/sqlite-mcp.service
[Unit]
Description=SQLite MCP Server
After=network.target

[Service]
Type=simple
User=mcp-user
WorkingDirectory=/opt/sqlite-mcp
Environment=SQLITE_DB_PATH=/data/production.db
Environment=MCP_LOG_LEVEL=INFO
ExecStart=/opt/sqlite-mcp/venv/bin/python -m mcp_server_sqlite
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Docker Production Setup

# Production Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
RUN pip install -e .

# Create non-root user
RUN groupadd -r mcp && useradd -r -g mcp mcp
USER mcp

EXPOSE 8080
CMD ["python", "-m", "mcp_server_sqlite", "--host", "0.0.0.0", "--port", "8080"]

Kubernetes Deployment

# kubernetes-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sqlite-mcp-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sqlite-mcp-server
  template:
    metadata:
      labels:
        app: sqlite-mcp-server
    spec:
      containers:
      - name: sqlite-mcp
        image: writenotenow/sqlite-mcp-server:latest
        ports:
        - containerPort: 8080
        env:
        - name: SQLITE_DB_PATH
          value: "/data/database.db"
        volumeMounts:
        - name: database-storage
          mountPath: /data
      volumes:
      - name: database-storage
        persistentVolumeClaim:
          claimName: sqlite-mcp-pvc

---

📚 Related Pages

• Quick-Start - Getting started guide
• Best-Practices - Usage recommendations
• Troubleshooting - Common issues and solutions
• Core-Database-Tools - Basic functionality

---

🔧 Installation Tip: Use Docker for the quickest start, but consider Python virtual environments for development and customization. Always test your installation with the built-in test suite.