# Using Turso MCP Server with AI Assistants: Complete Integration Guide

> Integrate Turso MCP server with AI assistants to execute SQL commands. Learn how to leverage JSON-RPC for seamless interaction with your database in this complete guide.

- Repository: [Turso Database/turso](https://github.com/tursodatabase/turso)
- Tags: how-to-guide
- Published: 2026-06-22

---

**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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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:

```json
{
  "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:

```bash
/path/to/tursodb --mcp

```

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

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

```

Open or create a database file:

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

```

Execute a read-only query:

```json
{
  "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:

```rust
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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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`](https://github.com/tursodatabase/turso/blob/main/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.