MCP Server

vi-sql includes a built-in MCP (Model Context Protocol) server that exposes your database to AI tools. This lets Claude, Cursor, or any MCP-compatible assistant:

Run SQL queries against your live database
Browse schema and table structure
Open tabs in the vi-sql UI
Generate and explain queries in context

tip

Security: By default AI tools can only browse your schema and push queries into the vi-sql editor — you stay in control of what actually runs. See the Security section below.

Enable the MCP server

The MCP server is started automatically when vi-sql is running and mcp.enabled is set to true in ~/.config/vi-sql/config.yaml:

yaml

mcp:
  enabled: true
  port: 9741 # default
  allowRead: false
  allowWrite: false

You can also toggle the MCP server from inside vi-sql via the actions palette (Ctrl+Space).

The server listens on http://127.0.0.1:<port>/mcp (default port 9741).

Connect to Claude

Add vi-sql to your Claude Desktop config at ~/.claude/claude_desktop_config.json:

json

{
  "mcpServers": {
    "vi-sql": {
      "url": "http://127.0.0.1:9741/mcp"
    }
  }
}

Or run this command once to register vi-sql with the Claude Code CLI:

claude mcp add --transport http vi-sql http://localhost:9741/mcp

Claude Code will now have access to the vi-sql MCP tools in every session while vi-sql is running.

Connect Cursor

In Cursor settings, add a new MCP server pointing to the HTTP endpoint:

json

{
  "mcpServers": {
    "vi-sql": {
      "url": "http://127.0.0.1:9741/mcp"
    }
  }
}

Available MCP tools

Tool	Description
`list_schemas`	List all schemas and their tables
`describe_table`	Return columns, constraints, foreign keys, and indexes for a table
`list_enum_types`	List custom enum types (PostgreSQL)
`sample_table`	Return up to N rows from a table (max 100)
`open_query_in_tab`	Pre-fill the SQL editor with a query without executing it
`get_query_from_tab`	Retrieve the current SQL text from an editor tab by ID
`update_query_in_tab`	Replace the SQL editor content of an existing tab without executing it
`get_last_query_result`	Return the result of the most recent query run in vi-sql
`read_query`	Run a SELECT/EXPLAIN query and return results (requires `allowRead`)
`write_query`	Run an INSERT/UPDATE/DELETE/DDL statement (requires `allowWrite`)
`explain_query`	Get the query plan, optionally with runtime stats via `analyze: true`
`get_server_info`	Return database version, name, and connection info

Security

By default, allowRead and allowWrite are both false. AI tools can browse schema and sample data, and can open or update queries in the vi-sql editor for you to review and run — but they cannot execute anything automatically. Enable the flags explicitly when needed:

Config	Effect
`allowRead: true`	Permits `read_query` (SELECT / EXPLAIN)
`allowWrite: true`	Permits `write_query` (INSERT / UPDATE / DELETE / DDL); also requires `allowRead: true`

Even with allowRead: true, read_query has a built-in SQL guard that strips comments and string literals, then rejects any query containing write keywords (INSERT, UPDATE, DELETE, DROP, ALTER, etc.). Only statements starting with SELECT, WITH, EXPLAIN, SHOW, TABLE, or VALUES are allowed through. This is an extra layer of protection on top of the config flags.

Use a read-only database user for additional protection when giving AI tools access to production data.