Docs / MCP server

MCP server

Give Claude, Cursor, Zed, Continue, and any other MCP client a walkindb_execute tool. One-line setup.

What this is

The walkindb MCP server adds two tools to any Model Context Protocol client:

• walkindb_execute(sql) — run one SQL statement against a private, ephemeral SQLite database. The first call in an MCP session provisions a new walk-in; subsequent calls in the same session reuse the same database until its 10-minute TTL expires.
• walkindb_reset() — forget the current session so the next walkindb_execute call provisions a fresh walk-in.

The server is a thin stdio wrapper over the walkindb JavaScript SDK. It speaks the standard Model Context Protocol and works with every MCP-compatible client.

Setup

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "walkindb": {
      "command": "npx",
      "args": ["-y", "walkindb-mcp"]
    }
  }
}

Restart Claude Desktop. In a new conversation, Claude now has walkindb_execute and walkindb_reset available under the MCP integration icon.

Claude Code

claude mcp add walkindb -- npx -y walkindb-mcp

Or edit .claude/mcp.json in your project directory:

{
  "mcpServers": {
    "walkindb": {
      "command": "npx",
      "args": ["-y", "walkindb-mcp"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "walkindb": {
      "command": "npx",
      "args": ["-y", "walkindb-mcp"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "walkindb": {
      "command": {
        "path": "npx",
        "args": ["-y", "walkindb-mcp"]
      }
    }
  }
}

Continue

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "walkindb-mcp"]
        }
      }
    ]
  }
}

Any other MCP client

walkindb-mcp speaks the standard Model Context Protocol over stdio. If your client can spawn a command and talk JSON-RPC on stdin/stdout, it works. The command is npx -y walkindb-mcp.

Environment variables

To set these in Claude Desktop / Cursor / etc., add an env key next to command / args:

{
  "mcpServers": {
    "walkindb": {
      "command": "npx",
      "args": ["-y", "walkindb-mcp"],
      "env": {
        "WALKINDB_BASE_URL": "https://my-walkindb.internal"
      }
    }
  }
}

What the tools return

walkindb_execute(sql)

On success, returns a JSON text block the model can parse:

{
  "columns": ["id", "body"],
  "rows": [[1, "hello"]],
  "rows_affected": 0,
  "truncated": false,
  "session_established": "wkn_AZ159u9PdmS97ks7...",
  "expires_at": 1775868670
}

The session_established field is a truncated identifier for the walk-in (the full token is never exposed to the model, only to the wire). expires_at is the unix timestamp at which the walk-in will be deleted.

On error, returns a text block with isError: true so the model can retry or back off:

walkindb error 400: forbidden sql keyword: ATTACH

walkindb_reset()

Returns a short confirmation. Does not delete the server-side walk-in — that still happens via the normal TTL sweeper within ~10 minutes.

First example, end to end

Once walkindb-mcp is wired into your client, prompt the model:

Create a SQLite table notes(id, body) and insert three rows using walkindb. Then query them back sorted by id descending.

You'll see three tool calls: one CREATE TABLE, one INSERT, one SELECT. All three reach the same walk-in because the MCP server holds the session token transparently across calls.

Good uses in an MCP client

• Agent planning memory. Let the agent record its own thoughts, decisions, and open questions in a plans table it can query later in the same conversation.
• RAG chunk staging. Pull 40 candidate chunks from your vector store, load them into a walk-in, rerank and dedupe with SQL, return the top 10.
• CSV analysis. User drops a CSV in the chat, agent loads it into a walk-in, runs GROUP BY / window queries, summarizes.
• Teaching SQL. Give the student a real database to poke at without making them install anything.

Bad uses

• PII or regulated data. See the AUP. The 10-minute TTL is a technical mitigation, not a legal one.
• Long-term memory. Walk-ins disappear after ~10 minutes. There is no paid tier.
• Secrets. Don't let the agent put credentials in a walk-in, even for a minute.

Under the hood

walkindb-mcp is a tiny stdio server (~160 lines of JavaScript) that wraps the walkindb npm package. It holds one Client instance for the lifetime of the MCP session — that's what makes the walk-in persist across walkindb_execute calls. When the MCP client disconnects, the server exits and the Client is garbage-collected; the walk-in itself survives on the server for the remainder of its 10-minute TTL.

The server source is three files: server.mjs, package.json, README.md. Read it at github.com/walkindb/walkindb/tree/main/stubs/mcp.

Also see

• JavaScript SDK — the client walkindb-mcp wraps
• REST API reference — what the SDK wraps
• Agent patterns — when to use walkindb
• Security model — what protects the walk-in contents
• walkindb-mcp on npm
• Model Context Protocol — the upstream spec