How to Do SQLite Setup on Claude Code (With MCP & Direct Access)

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, 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:

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:

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:

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 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 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 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).

Related Claude Code setup guides

If you're building out a full backend stack, these guides cover adjacent setup tasks that pair naturally with SQLite work:

• How to do Postgres database connection on Claude Code (for when you migrate off SQLite)
• How to do Docker container setup on Claude Code (containerize your SQLite app)
• How to do MongoDB connection on Claude Code (document store alternative)
• How to reduce Claude Code token usage (critical for database-heavy sessions)
• When does Claude Code usage reset (plan your database work around your limit window)

Monitor usage during long database sessions

SQLite schema work, migration writing, and iterative query debugging are the kind of tasks where you lose track of time and tokens simultaneously. Usagebar sits in your macOS menu bar and tracks your Claude Code usage in real time, firing alerts at 50%, 75%, and 90%. It stores your API credentials securely in the macOS Keychain, shows exactly when your usage window resets, and costs nothing (pay what you want, free for students).

Get Usagebar and stop discovering you've hit your limit right when you're finalizing a schema migration.

Sources

• Model Context Protocol: Quickstart for Users
• Model Context Protocol: Architecture Overview
• Anthropic Support: Using Claude Code with your Pro or Max plan
• Anthropic Support: Usage limit best practices