Skip to content

Quick Start

Jump to bottom
Temp edited this page Oct 9, 2025 · 3 revisions

Quick Start Guide

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

🚀 Quick Try

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

✅ Quick Test - Verify Everything Works

Test all 73 tools in 30 seconds:

# Quick smoke test (includes JSON helper tools)
python test_runner.py --quick

# Test JSON helper tools specifically
python test_runner.py --quick --json

# Standard comprehensive test (recommended)
python test_runner.py --standard

# Full test suite with edge cases
python test_runner.py --full

Expected output:

🚀 SQLite MCP Server Comprehensive Test Suite v2.6.3
================================================================

🔍 Environment Detection:
  ✅ SQLite 3.50.4 (JSONB supported)
  ✅ Python 3.12.11  
  ✅ MCP 1.14.0
  ✅ Pyright strict type checking: PASS

📊 Testing 73 Tools across 14 categories...

✅ Core Database Operations (15/15 passed)
✅ JSON Helper Tools (6/6 passed)
✅ Legacy Raw JSON SQL Ops (6/6 passed)
✅ Text Processing (8/8 passed)
✅ Statistical Analysis (8/8 passed)
✅ Advanced PRAGMA Operations (5/5 passed)
🎉 SUCCESS: 73/73 tools tested successfully!

**📝 Note on Legacy JSON Operations:** Legacy JSON SQL operations remain available (e.g., `json_extract`, `json_set`, `json_array`) - these are standard SQLite functions, not separate MCP tools. New projects should prefer JSON Helper Tools for enhanced security, auto-normalization, and better error diagnostics.

🎯 JSON Tools Status: ACTIVE
✅ 6 JSON helper tools: OPERATIONAL
✅ Auto-normalization: ENABLED
✅ Parameter serialization: ACTIVE

🛡️ Security Testing - SQL Injection Protection

TL;DR: Critical injection vectors blocked, parameter binding validated — overall posture: STRONG 🛡️

NEW: Comprehensive SQL injection vulnerability testing

# Test SQL injection protection (from tests directory)
cd tests && python test_sql_injection.py

# Expected result: 🛡️ Overall security posture: STRONG

What it tests:

  • Protection against the SQL injection vulnerability found in original Anthropic SQLite MCP server
  • 11 different attack vectors including multiple statements, UNION injection, blind injection
  • Parameter binding protection with malicious payloads
  • Stacked queries and comment-based injection attempts

Attack Vectors Tested:

  1. Multiple Statement Injection - SELECT 1; DROP TABLE users; ✅ BLOCKED
  2. UNION-based Information Disclosure - SELECT username UNION SELECT password_hash ⚠️ Executes (but safe, as these are legitimate SELECT queries, not injection)
  3. Boolean-based Blind Injection - Conditional queries to extract data ⚠️ Executes (but safe, as these are legitimate SELECT queries, not injection)
  4. Time-based Blind Injection - Queries that could cause delays ⚠️ Executes (but safe, as these are legitimate SELECT queries, not injection)
  5. Comment-based Injection - Using --, /* */, and # comments ✅ MOSTLY BLOCKED
  6. Stacked Queries with Various Separators - Different line endings ✅ BLOCKED
  7. Parameter Binding Protection - 6 malicious payloads with safe binding ✅ ALL SAFE
  8. String Concatenation Demo - Shows what would happen with unsafe code ⚠️ EDUCATIONAL

Security Assessment:

  • ✅ Critical attacks blocked: Multiple statements, stacked queries
  • ✅ Parameter binding working: All malicious payloads safely neutralized
  • ⚠️ Complex SELECT queries execute: This is expected behavior for valid SQL
  • 🛡️ Overall security posture: STRONG

Note: Error messages in the output are expected - they show the security protections working correctly by rejecting malicious queries.

📦 Getting Started

📋 Installation Requirements

  • Python 3.10+ – required runtime
  • SQLite 3.45.0+ – with JSONB support (current: 3.50.4)
  • MCP 1.14.0+ – Model Context Protocol library

Optional (advanced users):

  • Node.js 18+ – extra JSONB utilities (ESLint compliant)
  • Visual Studio C++ Build Tools – only for Node.js + better-sqlite3
  • ⚠️ Core server is Python-only and works without Node.js

Known Minor Issues

  • JSON formatting: Always use valid JSON with double quotes
  • Complex queries: Use parameter binding for advanced queries

🐍 Quick Start (Python)

# Auto-detect project root (default)
python start_sqlite_mcp.py

# Create organized data directory
python start_sqlite_mcp.py --create-data-dir

# Use specific database
python start_sqlite_mcp.py --db-path /path/to/database.db

# In-memory (testing only)
python start_sqlite_mcp.py --db-path :memory:

⚙️ MCP Client Configuration

Local Python:

{
  "mcpServers": {
    "sqlite-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/sqlite-mcp-server/start_sqlite_mcp.py",
        "--db-path", "/path/to/database.db"
      ]
    }
  }
}

Docker:

{
  "mcpServers": {
    "sqlite-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/host/project:/workspace",
        "writenotenow/sqlite-mcp-server:latest",
        "--db-path", "/workspace/database.db"
      ]
    }
  }
}

🐳 Docker Hub Deployment

Available on Docker Hub at writenotenow/sqlite-mcp-server.

# Pull latest version
docker pull writenotenow/sqlite-mcp-server:latest

# Pull specific version
docker pull writenotenow/sqlite-mcp-server:v2.6.3

🗄️ Database Configuration

  • Auto-creates sqlite_mcp.db in your project root if none exists because MCP operations require persistent storage between tool calls
  • Connects to existing databases - works with any SQLite file you specify
  • Supports both relative and absolute paths for maximum flexibility.

Database Location Best Practices

  • ./data/sqlite_mcp.db - Recommended for projects (organized, version-control friendly)
  • ./sqlite_mcp.db - Simple option for small projects
  • Existing databases - Use --db-path to connect to any SQLite database
  • :memory: - Temporary database for testing (data not persisted)

📚 Next Steps

After installation, explore these key areas:

📝 Need help? Check the Troubleshooting page or visit our GitHub Issues.

Clone this wiki locally