Basalt MCP server

Basalt A CLI-first local SQL workspace for structured data and coding agents.

Basalt is an embedded SQL database and command-line application built from scratch in Rust. It provides a small library API, an interactive shell, durable storage, snapshot-isolated transactions, crash recovery, portable structured-data workspaces, and a stdio MCP server for local AI agents. It is not a SQLite-compatible replacement or a hosted database.

Highlights

aggregates, aliases, and transaction statements.

• SQL lexer and recursive-descent parser with expressions, joins, grouping,

indexes.

• Atomic statement execution with primary-key, UNIQUE, and user-created

state after a process crash.

• Snapshot-isolated transactions with optimistic conflict detection.
• Checksummed page snapshots and a write-ahead log that recovers committed

SQL dump import/export.

• Simple query planning with table scans, equality indexes, and range indexes.
• Interactive and scriptable CLI output in table, CSV, and JSON-lines formats.
• Portable workspaces with versioned metadata and atomic CSV, JSON/JSONL, and

exports, engine-bounded SQL, schema resources, and recoverable agent changes.

• Installable MCP server with typed SQL tools, bounded workspace imports and

Installation

Rust 1.88 or newer is required for a Cargo install.

cargo install basalt-db --locked

The published package is named basalt-db; the installed command remains basalt. To install the current checkout instead, use cargo install --path . --locked.

Tagged releases include checksummed installers and prebuilt binaries for Linux, macOS, and Windows. See GitHub Releases for the current no-toolchain install. The latest tagged release is verified from its published installer and its checksums:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/yoshiii-xyz/basalt/releases/latest/download/basalt-db-installer.sh | sh

To run directly from a checkout:

cargo run --release -- app.basalt

Quick start

Open a database and run SQL interactively:

$ basalt app.basalt
basalt> CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
basalt> INSERT INTO users VALUES (1, 'Ada');
basalt> SELECT * FROM users;
id | name
---+-----
1  | Ada
1 row(s)

For a one-shot command:

basalt --json --command "SELECT * FROM users ORDER BY id;" app.basalt

Use Database::in_memory() for an ephemeral database. Durable writes are appended to the WAL immediately; call checkpoint() to fold the current state into the snapshot and clear old WAL frames. A durable path is owned by one process at a time; cloned Database handles share that owner safely across threads, while a second process receives an "already open" error.

Workspaces

Use a workspace when an agent or script needs a disposable, local relational area for CSV, JSON, logs, issue exports, or fixtures:

basalt init .basalt-workspace
basalt workspace import --table issues .basalt-workspace issues.csv
basalt workspace inspect --json .basalt-workspace
basalt workspace query --json .basalt-workspace "SELECT * FROM issues ORDER BY id"
basalt workspace export .basalt-workspace issues issues.jsonl

Shortened. The full README is on GitHub.