home / mcp / spotdb mcp server
Provides a lightweight data sandbox with MCP and REST interfaces for safe AI-driven data exploration.
Configuration
View docs{
"mcpServers": {
"aliengiraffe-spotdb": {
"url": "http://localhost:8081/stream"
}
}
}SpotDB provides a lightweight, ephemeral data sandbox that lets you explore data with AI while enforcing guardrails and security. It exposes data through an MCP interface and a REST API, enabling safe, isolated analysis without touching production databases.
You can use SpotDB by running the local server, uploading data, and querying it through either the MCP interface or the REST API. You can also connect an MCP client (like Claude Code) to run data analysis workflows against your sandbox. Use the Explorer UI to upload files and run queries in a browser.
Typical usage patterns include starting SpotDB, adding a CSV as a table, and performing SQL-like queries to inspect results. You can also set up an MCP integration to drive AI-powered analysis and keep data isolated from production systems.
Prerequisites: you need a Unix-like environment with a shell, Homebrew for macOS users, and network access to run local commands.
# Install the SpotDB package via Homebrew
brew tap aliengiraffe/spaceship && \\
brew install spotdb
# Start the SpotDB server
spotdb
# Optional: upload a CSV file to create a table
curl -X POST \
http://localhost:8080/api/v1/upload \
-F "table_name=mytable" \
-F "has_header=true" \
-F "[email protected]"
# Optional: query the data
curl -X POST \
http://localhost:8080/api/v1/query \
-H "Content-Type: application/json" \
-d '{"query": "SELECT * FROM mytable LIMIT 10"}'
# Optional: connect an MCP client (example with Claude Code)
claude mcp add spotdb -s user -- npx -y mcp-remote http://localhost:8081/stream
# Open the Explorer UI
open http://localhost:8080/explorerSpotDB can be interacted with in two main ways: via the MCP channel for AI models and workflows, or via the REST API for traditional integrations. The REST API exposes endpoints to upload data and run queries, while the MCP path lets you hook SpotDB into AI agents and automated pipelines.
You will typically run SpotDB locally and connect your MCP client or UI to the provided local endpoints. The REST API endpoint for uploads is http://localhost:8080/api/v1/upload and the query endpoint is http://localhost:8080/api/v1/query. The Explorer UI is accessible at http://localhost:8080/explorer.
The following MCP configurations enable remote and local access to SpotDB for MCP-based workflows. The HTTP-based MCP URL is used for remote clients, and a local stdio command starts SpotDB directly.
{
"mcpServers": [
{
"type": "http",
"name": "spotdb_http",
"url": "http://localhost:8081/stream",
"args": []
},
{
"type": "stdio",
"name": "spotdb",
"command": "spotdb",
"args": []
}
]
}SpotDB is designed to prevent accidental changes to production data. It enforces guardrails to limit data exposure and maintain privacy during AI-driven analysis. Run in an isolated sandbox and avoid direct access to production databases when using AI agents.
If you cannot access the REST API, verify that SpotDB is running and reachable at http://localhost:8080. If using MCP, ensure the remote MCP URL is reachable (for example, http://localhost:8081/stream) and that your MCP client is configured to connect to SpotDB.
This sandbox supports ephemeral databases, capture of data snapshots, REST API access, and MCP API access for AI workflows. Use the Explorer UI to interact with data visually and keep operations isolated from production systems.
Upload a CSV file to create a new table in the sandbox using the REST API.
Execute SQL-like queries against the uploaded data via the REST API.
Capture and manage point-in-time data snapshots for recovery and state continuation.
Integrate SpotDB with MCP workflows by linking an MCP client to the local sandbox.
Open and use the web-based Explorer UI to upload files and run queries.