SpotDB: DuckDB SQL sandbox for agents
SpotDB
A temporary DuckDB sandbox: an agent loads a CSV and queries the data over MCP or REST without touching the production database
- 21 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent runs SQL in the sandbox, including `write_query` with INSERT, UPDATE and DELETE
- An uploaded CSV may hold personal data, and the agent will see it in full
Install
- Works in
Manual install
brew tap aliengiraffe/spaceship && brew install spotdbInstallation from the README, then start it with spotdb.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent runs SQL in the sandbox, including `write_query` with INSERT, UPDATE and DELETE
- An uploaded CSV may hold personal data, and the agent will see it in full
This is third-party code. Review the repository files before installing.
What it does
SpotDB starts a temporary DuckDB database on your machine and wraps it in an API with guardrails. The agent and scripts work only with that copy of the data, so production databases stay out of reach. A CSV file loads in one request, and the server infers the schema and column types itself. There are two ways in. The REST API listens on port 8080 and accepts file uploads and SQL queries, while the MCP server on port 8081 gives the agent the same abilities over SSE and Streamable HTTP. MCP tools include `read_query`, `write_query`, `create_datasource`, `list_datasources`, `load_datasource`, `describe_datasource` and `append_insight` for notes on the analysis. Snapshots save a state of the data so you can return to it later. For browsing without an agent there is the Explorer web interface at localhost:8080/explorer, where you can upload a file and run a query by hand.
Who it is for. Analysts and developers who want an agent to work with a CSV export without opening up the production database.
Good fit when
- A CRM export needs SQL analysis, and the agent must not be connected to the CRM itself
- You want quick analytics on a CSV without writing a schema or running a separate database
- The agent should keep notes on its analysis findings, collected in a memo about the data
- Before a risky transformation you save a snapshot and roll back to it on a mistake
Not a fit when
- Data lives in a production database and updates constantly: the sandbox works with an uploaded copy
- You need a database for an application: the store is temporary and meant for analysis, not for a service
- The server must be opened to several users: the README describes one instance per machine
- Your files are not CSV: the README describes uploading only that format
Example request
Load orders.csv into the sandbox, describe the table structure and find the five customers with the largest order totals.MCP
- Transport
- http, sse
- Authentication
- not required
Environment variables
X-API-Keysecret- Optional key for request authentication
Limitations
The store is temporary: sandbox data lives while it runs, and snapshots are needed to keep it.
The README and the documentation disagree on write access: the documentation calls the environment read-only, yet the MCP tools include `write_query` for INSERT, UPDATE and DELETE. Judge the agent's rights by the tools, not by the description.
Claude Code connects through the `mcp-remote` bridge, so Node.js is required. Installation goes through Homebrew, and the README gives no separate commands for other systems.
How to disable. Stop the spotdb process and remove the server with claude mcp remove spotdb. The temporary sandbox data disappears with the stop.
FAQ
How do I install SpotDB for Claude Code?
Run brew tap aliengiraffe/spaceship and brew install spotdb, start the spotdb command, then claude mcp add spotdb -s user -- npx -y mcp-remote http://localhost:8081/stream. The claude command must be installed first.
How do I upload a CSV?
POST the file to http://localhost:8080/api/v1/upload with the fields table_name, has_header and csv_file. After that queries go to /api/v1/query or through MCP.
How is SpotDB different from connecting the agent to a database directly?
The agent sees only the uploaded copy in DuckDB, and access goes through an API with limits. Production data and its credentials stay on your side.
Does the server use a key?
The MCP Registry entry lists an optional request key, X-API-Key. The local run in the README does not need it.
Where can I look at the data without an agent?
Open http://localhost:8080/explorer: you can upload files and run queries by hand there.
Discussion
No questions or reviews yet.
Related
MCP serversThe MCP server of the Duckle platform: an agent builds, checks and runs DuckDB ETL pipelines on your machine
DuckDB / MotherDuck MCP Server
DuckDB / MotherDuck Local MCP Server
An MCP server for SQL analytics on DuckDB: local files, in-memory databases, S3-hosted databases and MotherDuck
A lightweight database workspace with an MCP server: the agent reads the schema, runs queries and explores data in PostgreSQL, MySQL and more
A desktop SQL workspace with a built-in MCP server: the agent reads the schema and runs queries in the same client you already use
One MCP server for SQLite, SQL Server, PostgreSQL and MySQL: read and change data, edit schemas and export to CSV and JSON
A token-lean MCP server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| SpotDB: DuckDB SQL sandbox for agents (this card) | yes | not required | 21 | |
| DuckDB / MotherDuck MCP Server | yes | not required | 539 | a server for existing DuckDB files and the MotherDuck cloud, without CSV upload and snapshots |
| duckdb-skills | no | 616 | a set of skills for DuckDB work in the agent rather than a standalone sandbox server |
README in short
The README opens with a quick start: Homebrew installation, starting the server, uploading a CSV with curl, running a SQL query and connecting MCP to Claude Code. Detailed documentation lives in DOCS.md, and the repository describes the project as a lightweight data sandbox with guardrails for AI workflows.