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.

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"]
    }
  }
}

Tools (30)

Query and Analysis

Transaction Control

Schema Inspection

Schema Modification

Database Administration

Auto-injected Instructions

The server provides built-in MCP instructions that are automatically sent to the AI during the connection handshake. This means any AI client receives a comprehensive Stoolap SQL reference on connect, covering data types, supported syntax, all operator categories, index types, vector search, transaction isolation levels, and known limitations, without the user needing to configure anything. The AI can write correct Stoolap SQL from the first query.

For deeper reference (live schema + full function signatures), attach the sql-assistant prompt.

Resources

Prompts

SQL Coverage

The MCP server exposes the full Stoolap SQL surface through the query and execute tools:

• 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
• Window functions: ROW_NUMBER, RANK, DENSE_RANK, NTILE, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTH_VALUE, PERCENT_RANK, CUME_DIST (plus all aggregates with OVER)
• GROUP BY extensions: ROLLUP, CUBE, GROUPING SETS, GROUPING()
• Aggregates: COUNT, SUM, AVG, MIN, MAX, MEDIAN, STRING_AGG, ARRAY_AGG, STDDEV, VARIANCE, and more
• 100+ scalar functions: string, math, date/time, JSON, hash, conditional, vector, type conversion
• Operators: arithmetic, comparison, logical, bitwise, LIKE/ILIKE/GLOB/REGEXP, JSON (->/->>), vector (<=>), BETWEEN, IN, IS [NOT] DISTINCT FROM, INTERVAL
• Transactions: BEGIN with isolation levels (READ COMMITTED, SNAPSHOT), COMMIT, ROLLBACK, SAVEPOINT
• Temporal queries: AS OF TIMESTAMP, AS OF TRANSACTION
• Index types: BTree, Hash, Bitmap, HNSW (vector), Unique, Composite
• Vector search: k-NN with L2, cosine, inner product distances and HNSW indexing
• EXPLAIN / EXPLAIN ANALYZE for query plan inspection

Options

Requirements

• Node.js >= 18
• The @stoolap/node package (installed automatically as a dependency)

The Stoolap native addon is bundled with @stoolap/node via prebuilt binaries for Linux (x64, arm64) and macOS (x64, arm64).

Building from Source

git clone https://github.com/stoolap/stoolap-mcp.git
cd stoolap-mcp
npm install
npm run build
node build/index.js --path ./mydata

License

Apache-2.0