stoolap-mcp

MCP (Model Context Protocol) server for Stoolap, an embedded SQL database. Lets AI assistants query, manage, and analyze Stoolap databases with full access to all SQL features.

Works with any MCP-compatible AI client: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and others.

Version 0.4.x of this server targets the Stoolap 0.4.x engine (volume-based storage) through @stoolap/node.

Registry

The server is published to the MCP Registry as io.github.stoolap/mcp. server.json in this repository is the registry manifest; its version and the mcpName field in package.json are kept in step with the npm package.

Related MCP server: sqlite-mcp-server

Quick Start

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "stoolap": {
      "command": "npx",
      "args": ["-y", "@stoolap/mcp", "--path", "./mydata"]
    }
  }
}

Claude Code

claude mcp add stoolap -- npx -y @stoolap/mcp --path ./mydata

In-memory (no persistence)

{
  "mcpServers": {
    "stoolap": {
      "command": "npx",
      "args": ["-y", "@stoolap/mcp"]
    }
  }
}

Read-only mode

{
  "mcpServers": {
    "stoolap": {
      "command": "npx",
      "args": ["-y", "@stoolap/mcp", "--path", "./mydata", "--read-only"]
    }
  }
}

Options

The first npx run compiles the small native addon of @stoolap/node, which can take a while; MCP clients with a short startup timeout may report a failed connection on that first run. Retry once the install has finished, or install the package globally beforehand (npm install -g @stoolap/mcp).

Tools (30)

Every tool carries MCP annotations (readOnlyHint, destructiveHint), so clients can auto-approve the read-only ones.

Query and Analysis

Transaction Control

Schema Inspection

Schema Modification

Database Administration

Auto-injected Instructions

The server sends MCP instructions during the connection handshake, so any AI client receives a compact Stoolap SQL reference on connect: data types, tool routing, upsert syntax, index and vector rules, transaction rules, and the known limitations of the 0.4.x engine.

For the full reference with the live schema, attach the sql-assistant prompt or read stoolap://sql-reference.

Resources

Prompts

SQL Coverage

• 7 data types: INTEGER, FLOAT, TEXT, BOOLEAN, TIMESTAMP, JSON, VECTOR(N)

• Joins: INNER, LEFT, RIGHT, FULL OUTER, CROSS, NATURAL, self-joins, multi-table

• Subqueries: scalar, IN/NOT IN, EXISTS/NOT EXISTS, ANY/SOME/ALL, correlated, derived tables

• CTEs: WITH, WITH RECURSIVE, multiple CTEs, column aliases, WITH before INSERT/UPDATE/DELETE

• Window functions: ROW_NUMBER, RANK, DENSE_RANK, NTILE, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTH_VALUE, PERCENT_RANK, CUME_DIST, every aggregate with OVER, named windows

• Aggregates: 17 functions with DISTINCT and FILTER; GROUP BY ROLLUP, CUBE, GROUPING SETS; DISTINCT ON

• Scalar functions: 98 functions across string, math, date/time, JSON, hash, conditional, type and vector categories

• Upsert: ON CONFLICT DO UPDATE / DO NOTHING with EXCLUDED, ON DUPLICATE KEY UPDATE

• Bulk load: COPY table FROM 'file.csv' WITH (FORMAT CSV, HEADER true)

• Transactions: READ COMMITTED and SNAPSHOT isolation, savepoints

• Temporal queries: AS OF TIMESTAMP, AS OF TRANSACTION

• Indexes: BTree, Hash, Bitmap, HNSW (vector), unique, composite

• Vector search: k-NN with L2, cosine and inner product distances, HNSW indexing

• EXPLAIN / EXPLAIN ANALYZE

Safety

• Single statement per call: the engine executes every statement of a multi-statement string but reports only the last one, so semicolon-separated batches are rejected.

• Tool routing: query accepts only read statements, execute is blocked while a transaction is open, and transaction control statements (BEGIN, COMMIT, ROLLBACK, SAVEPOINT) are only reachable through the transaction tools, so the server always knows the connection's transaction state.

• Read-only mode rejects every write, including COPY, DDL, SET, ANALYZE, VACUUM and PRAGMA actions.

• COPY ... FROM reads files on the host with the server process's permissions, so an assistant can load any readable file into a table. Run with --read-only when that is not acceptable.

• DDL outside transactions: only CREATE TABLE is rolled back reliably by the engine, so DDL, TRUNCATE and COPY are refused inside a transaction.

• EXPLAIN ANALYZE is refused for write statements because it executes them.

• Injection guards: table and view names are double-quoted, savepoint and pragma names must be bare identifiers, pragma values are validated per pragma.

• The database is closed cleanly (open transaction rolled back, checkpoint on close) when the client disconnects or the process receives SIGINT/SIGTERM.

Requirements

• Node.js >= 20

• @stoolap/node (installed automatically) with prebuilt engine libraries for Linux (x64, arm64), macOS (x64, arm64) and Windows (x64). A C compiler is needed for its small N-API addon. CI exercises Linux and macOS.

Development

git clone https://github.com/stoolap/stoolap-mcp.git
cd stoolap-mcp
npm install
npm test          # builds, then runs the end-to-end smoke tests against the built server
node build/index.js --path ./mydata

Releases are published to npm from the v* tag workflow using npm trusted publishing (OIDC); no token is needed.

License

Apache-2.0