To set up SQLite on Claude Code, the fastest path is using the **official `@modelcontextprotocol/server-sqlite` MCP server**, which gives Claude direct read/write access to your `.db` files. Alternatively, Claude Code's built-in Bash tool can run `sqlite3` commands without any extra configuration. Both approaches work on macOS and Linux. SQLite setup is lightweight and session-safe, but heavy schema exploration across large databases burns tokens fast, so monitor your usage before you start. ## What is SQLite access in Claude Code? Claude Code can interact with SQLite databases in two distinct ways: through a **Model Context Protocol (MCP) server** that exposes structured database tools, or by invoking the system `sqlite3` CLI directly through its Bash tool. The MCP approach gives Claude named tools like `query`, `list-tables`, and `describe-table`, which produce cleaner, more structured output. The Bash approach requires no setup but gives Claude raw shell access. For most development workflows, the MCP server is the better choice. It scopes Claude's access to a specific database file and produces structured results that are easier to reason about. The Bash fallback is useful for quick one-off queries or when you're already using Claude Code without any MCP configuration. ## How to set up the SQLite MCP server on Claude Code According to the [Model Context Protocol quickstart](https://modelcontextprotocol.io/quickstart/user), the SQLite MCP server is one of the officially supported servers maintained by Anthropic. Here's how to add it to your Claude Code project. ### Step 1: Install the MCP server Run the following command in your project root. Claude Code will add it to your local `.mcp.json` configuration file: ```bash claude mcp add @modelcontextprotocol/server-sqlite --args /path/to/your/database.db ``` Replace `/path/to/your/database.db` with the actual path to your SQLite file. If the file doesn't exist yet, the server will create it on first use. ### Step 2: Verify the MCP server is registered Check that the server was added correctly: ```bash claude mcp list ``` You should see `@modelcontextprotocol/server-sqlite` in the output with a status of "connected" when Claude Code is running. ### Step 3: Start a session and test access Open a Claude Code session and ask it to inspect the database: ``` claude > List all tables in the database > Describe the schema for the users table ``` Claude will use the MCP tools automatically. You don't need to reference the server by name in your prompts. ### Step 4: Run queries Once connected, Claude can execute arbitrary SQL against your database: ``` > SELECT * FROM orders WHERE status = 'pending' LIMIT 10 > Create an index on the email column of the users table > Insert a test record into the products table ``` The MCP server handles the execution and returns structured results back to Claude's context window. ## How to use SQLite via the Bash tool (no MCP setup needed) If you'd rather skip MCP configuration entirely, Claude Code's built-in Bash tool can call `sqlite3` directly as long as it's installed on your system. On macOS, `sqlite3` ships with the OS. On Linux, install it with `apt install sqlite3` or the equivalent for your distribution. Just describe what you need and Claude will construct the shell commands: ``` > Run a query against ./data/app.db to get all users created in the last 7 days > Show me the schema of ./data/app.db using sqlite3 ``` Claude will execute something like: ```bash sqlite3 ./data/app.db "SELECT * FROM users WHERE created_at >= date('now', '-7 days');" sqlite3 ./data/app.db ".schema" ``` This approach is fast for exploration but gives Claude broader shell access. For production databases, the scoped MCP approach is safer. ## Configuring MCP server scope and permissions The [MCP architecture](https://modelcontextprotocol.io/docs/concepts/architecture) supports both local (stdio) and remote (HTTP) server types. The SQLite server runs locally over stdio, meaning it never sends your data over the network. All access is scoped to the single database file you provide as an argument. You can configure the server at three scopes in Claude Code: - **Project scope** (`.mcp.json` in project root): shared with the team, committed to version control - **Local scope** (`.mcp.json` in your home directory): personal overrides, not shared - **Global scope**: available across all Claude Code sessions on your machine For most SQLite setups, project scope is the right choice. It means any developer who clones the repo and runs `claude mcp install` gets the same database access configuration automatically. ## Token usage considerations for SQLite work Database-heavy sessions are one of the fastest ways to hit Claude's usage limits. Schema exploration, iterative query refinement, and large result sets all consume tokens quickly. Claude's context window includes every query result, every table description, and every error message the MCP server returns. On large databases, a single "describe all tables" request can consume a significant chunk of your session budget. A few practices that help: - Ask Claude to describe tables one at a time rather than all at once - Use `LIMIT` clauses aggressively during exploration - Compress the context with `/compact` before switching from exploration to writing migration code - Start a fresh session once you've mapped the schema and know what you need to build If you're working on a large schema refactor or building out migrations, it's easy to exhaust your Claude Code usage mid-task without realizing it. The frustration of getting locked out with 5 hours left on the reset clock, right when you're wrapping up a PR, is real. [Usagebar](/content/site-root.html) shows your live usage in the macOS menu bar and alerts you at 50%, 75%, and 90% so you can make a call before you're cut off. You can also check your current usage mid-session with the [`/usage` slash command](/content/blog/how-do-i-check-my-claude-code-usage-limits/index.html) inside Claude Code, or by visiting `claude.ai/settings/usage` in your browser. ## Comparison: MCP server vs Bash tool for SQLite | Approach | Setup required | Access scope | Output format | Best for | |-------------------------------|--------------------------------------|------------------|---------------|------------------------------------------| | MCP server (`server-sqlite`) | One command (`claude mcp add`) | Single `.db` file | Structured JSON | Team projects, repeated access | | Bash tool (`sqlite3` CLI) | None (sqlite3 must be installed) | Any file the shell can reach | Raw text | Quick one-off queries, scripting | ## Common issues with SQLite setup on Claude Code ### MCP server not connecting If `claude mcp list` shows the server as disconnected, check that Node.js is installed and that the path to your `.db` file is absolute, not relative. The MCP server process starts from Claude Code's working directory, which may differ from your project root. ### Permission denied on the database file SQLite files need read/write permissions for the user running Claude Code. Run `chmod 664 ./your-database.db` if you're seeing permission errors in the MCP output. ### Database locked errors SQLite uses file-level locking. If another process (your dev server, a test runner) has the database open with a write lock, Claude's queries will fail with "database is locked." Stop the other process or use a separate test database for Claude Code sessions. ### sqlite3 not found in Bash tool On some Linux distributions, `sqlite3` is not installed by default. Ask Claude to check: `which sqlite3`. If missing, install it with `sudo apt install sqlite3` (Debian/Ubuntu) or `sudo yum install sqlite` (RHEL/CentOS).