Using Turso MCP Server with AI Assistants: Complete Integration Guide

The Turso CLI ships with a built-in Model Context Protocol (MCP) server that enables AI assistants to execute SQL commands via JSON-RPC over stdin/stdout by launching tursodb --mcp.

Turso is an edge database built on SQLite, and the tursodatabase/turso repository includes a native MCP server that bridges the gap between large language models and local database operations. This integration allows AI assistants to query, modify, and inspect Turso databases through a standardized protocol without exposing raw file system access.

How the Turso MCP Server Works

The MCP server implementation transforms the standard Turso CLI into a JSON-RPC server that AI tools can invoke programmatically.

Entry Point and CLI Flag

The tursodb binary exposes a --mcp flag defined in cli/app.rs (lines 79-80). When present, the CLI bypasses the interactive REPL and initializes TursoMcpServer instead. This mode keeps the process alive to handle multiple requests over a single session, maintaining persistent database connections until the AI client disconnects or sends a termination signal.

JSON-RPC Transport Layer

The server communicates via line-delimited JSON objects over stdin and stdout. In cli/mcp_server.rs (lines 69-76), the main loop reads incoming requests from stdin, parses them as JSON-RPC 2.0 messages, and writes responses back to stdout. Each request must contain:

• jsonrpc: "2.0"
• id: A unique identifier (or omitted for notifications)
• method: The operation name
• params: Optional arguments object

This transport design allows AI assistants to spawn the process once and maintain a long-running pipe for multiple database operations.

Core Request Methods

The server implements three primary MCP protocol methods:

1. initialize – Returns server version and capability declarations (lines 74-90 in cli/mcp_server.rs)
2. tools/list – Enumerates available database tools including open_database, query, execute, list_tables, and describe_table (lines 92-99)
3. tools/call – Dispatches tool invocations to the appropriate database helpers (lines 100-111)

Database Connection Management

The server maintains an Arc<Mutex<Arc<Connection>>> (conn) shared across all tool calls. When an AI assistant first invokes open_database with a file path, the server creates a Connection via the Turso core library (turso_core::Connection) and stores it in self.conn. Subsequent tool calls reuse this connection, enabling transactional consistency across multiple AI-generated queries without reconnecting.

Interrupt Handling

The implementation monitors a shared AtomicUsize (interrupt_count) during each loop iteration (lines 98-101). If the process receives SIGINT or a similar signal, the counter increments and the server exits gracefully, preventing orphaned database locks when AI assistants terminate unexpectedly.

Available MCP Tools for AI Assistants

The Turso MCP server exposes a curated toolset designed specifically for LLM interaction, documented in cli/manuals/mcp.md. Each tool follows a strict JSON schema that AI models can generate reliably:

• open_database – Creates or opens a database file at a specified path
• query – Executes read-only SQL statements (SELECT) and returns result sets
• execute – Runs write statements (INSERT, UPDATE, DELETE, CREATE TABLE)
• list_tables – Returns all tables in the current database
• describe_table – Shows schema information for a specific table

This fine-grained approach follows the principle of least privilege, granting AI assistants database operations without raw file system access.

Configuring AI Assistants to Use Turso

Claude Desktop Configuration

Add the Turso MCP server to your Claude Desktop configuration file:

{
  "mcpServers": {
    "turso": {
      "command": "/path/to/tursodb",
      "args": ["--mcp"]
    }
  }
}

Claude will automatically spawn the process when needed and route database queries through the MCP protocol.

Manual Testing with Raw JSON-RPC

You can test the server manually by launching it from the terminal:

/path/to/tursodb --mcp

Then send line-delimited JSON commands. Initialize the session first:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {}
  }
}

Open or create a database file:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "open_database",
    "arguments": { "path": "/tmp/example.db" }
  }
}

Execute a read-only query:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": { "sql": "SELECT * FROM users" }
  }
}

Programmatic Integration Example

For custom AI assistants, implement a Rust client using serde_json to manage the stdin/stdout pipe:

use std::io::{Write, BufRead, BufReader};
use std::process::{Command, Stdio};

fn main() -> anyhow::Result<()> {
    // Spawn the MCP server
    let mut child = Command::new("/path/to/tursodb")
        .arg("--mcp")
        .stdin(Stdio::piped())
        .stdout(Stdio::piped())
        .spawn()?;

    let mut stdin = child.stdin.take().unwrap();
    let stdout = child.stdout.take().unwrap();
    let mut reader = BufReader::new(stdout);

    // Helper to send a request and read the response line
    let mut send = |req: serde_json::Value| -> serde_json::Value {
        writeln!(stdin, "{}", req).unwrap();
        let mut line = String::new();
        reader.read_line(&mut line).unwrap();
        serde_json::from_str(&line).unwrap()
    };

    // Initialise
    let init = json!({
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {}
    });
    println!("Init response: {:#}", send(init));

    // Open a DB
    let open = json!({
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": { "name": "open_database", "arguments": { "path": "/tmp/example.db" } }
    });
    println!("Open response: {:#}", send(open));

    // Query
    let query = json!({
        "jsonrpc": "2.0",
        "id": 3,
        "method": "tools/call",
        "params": { "name": "query", "arguments": { "sql": "SELECT * FROM users" } }
    });
    println!("Query response: {:#}", send(query));

    Ok(())
}

Summary

• Turso MCP server is activated via the --mcp flag in cli/app.rs, switching the CLI from interactive mode to JSON-RPC server mode.
• Transport layer uses line-delimited JSON over stdin/stdout implemented in cli/mcp_server.rs, supporting the MCP protocol methods initialize, tools/list, and tools/call.
• Database state persists across AI assistant requests through an Arc<Mutex<Arc<Connection>>> initialized by the open_database tool.
• Tool security restricts AI assistants to specific SQL operations (query, execute, schema inspection) rather than raw file access.
• Integration works with Claude Desktop via JSON configuration or custom clients using any language that can spawn processes and handle JSON-RPC.

Frequently Asked Questions

How do I start the Turso MCP server for AI assistants?

Launch the Turso CLI binary with the --mcp flag: /path/to/tursodb --mcp. This starts the JSON-RPC server that listens on stdin and writes responses to stdout, as implemented in cli/mcp_server.rs. The server remains active until the AI assistant closes the pipe or sends an interrupt signal.

What database operations can AI assistants perform through the MCP server?

AI assistants can invoke five primary tools: open_database to connect to a file, query for read-only SELECT statements, execute for write operations (INSERT, UPDATE, DELETE, DDL), list_tables to see all tables, and describe_table to inspect schemas. These tools are dispatched through the tools/call method in cli/mcp_server.rs (lines 100-111).

Why does the Turso MCP server use stdin/stdout instead of HTTP?

The stdin/stdout transport allows AI assistants to spawn the tursodb --mcp process as a child and maintain a persistent, stateful connection without network ports or authentication complexity. This design, found in cli/mcp_server.rs (lines 69-76), enables secure local operation where the AI tool controls the process lifecycle directly.

Can multiple AI assistants connect to the same Turso database simultaneously through MCP?

Each MCP server instance manages one Connection object stored in self.conn. While a single server process can handle sequential requests from one AI assistant, multiple assistants require separate tursodb --mcp processes. Each process opens its own database connection, though SQLite's file locking ensures consistency when accessing the same database file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}