playbooks

home / mcp / turso cloud mcp server

Turso Cloud MCP Server

🗂️ A Model Context Protocol (MCP) server that provides integration with Turso databases for LLMs. This server implements a two-level authentication system to handle both organization-level and database-level operations, making it easy to manage and query Turso databases directly from LLMs.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "spences10-mcp-turso-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-turso-cloud"
      ],
      "env": {
        "TURSO_API_TOKEN": "your-turso-api-token",
        "TOKEN_EXPIRATION": "7d",
        "TOKEN_PERMISSION": "full-access",
        "TURSO_ORGANIZATION": "your-organization-name",
        "TURSO_DEFAULT_DATABASE": "optional-default-database"
      }
    }
  }
}

You have a two-level MCP server that integrates Turso databases with LLMs, enabling organization-wide and database-specific actions from your AI workflows. You can manage databases, run queries, and perform vector searches securely while controlling destructive operations with explicit approval when needed.

How to use

To use this MCP server, configure your MCP client with the provided server options. You’ll authenticate at the organization level with your Turso Platform API token to manage databases and organization-wide actions, and you’ll obtain database-specific tokens for database-level operations. Use read-only queries for safe data retrieval and write/delete/DDL operations only when you have explicit approval. You can list databases, create or delete them, generate tokens for specific databases, list tables, run read-only queries, execute destructive queries, describe table schemas, and perform vector similarity searches against SQLite vector extensions.

- Organization-level actions include listing databases, creating databases, deleting databases, and generating tokens for individual databases. - Database-level actions include listing tables, executing read-only queries, executing potentially destructive queries, describing tables, and performing vector searches. - For destructive actions, review the query carefully before approving execution to prevent unintended data changes.

How to install

Prerequisites you need before running the MCP server: Node.js and npm installed on your system.

Step 1: Install dependencies for the MCP server codebase.

Step 2: Build the project to produce runnable artifacts.

Step 3: Start the server in development mode to test locally.

Configuration and security notes

Two-level authentication is used to separate organization-wide access from database-specific operations.

Environment variables you will typically provide when running the server include: TURSO_API_TOKEN, TURSO_ORGANIZATION, TURSO_DEFAULT_DATABASE, TOKEN_EXPIRATION, and TOKEN_PERMISSION. These variables control authentication, default database selection, and token lifetimes/permissions.

Always review SQL queries before executing destructive operations. Use read-only queries for safe data access and require explicit approval for actions that can modify or delete data.

Config examples for MCP clients

{
  "mcpServers": {
    "turso_cloud": {
      "command": "npx",
      "args": ["-y", "mcp-turso-cloud"],
      "env": {
        "TURSO_API_TOKEN": "your-turso-api-token",
        "TURSO_ORGANIZATION": "your-organization-name",
        "TURSO_DEFAULT_DATABASE": "optional-default-database"
      }
    }
  }
}

Troubleshooting

If you encounter authentication or connection issues, verify that your Turso API token is valid, your organization name is correct, and the token has the necessary permissions. Make sure the specified database exists and that the token has access to it.

Notes

This MCP server supports a two-level authentication flow and a mix of read-only and writable SQL operations. Plan your queries accordingly and rely on the read-only path for safe data access whenever possible.

Available tools

list_databases

Lists all databases in your Turso organization.

create_database

Creates a new database in your organization.

delete_database

Deletes a database from your organization.

generate_database_token

Generates a new token for a specific database.

list_tables

Lists all tables in a database.

execute_read_only_query

Executes a read-only SQL query (SELECT, PRAGMA) against a database.

execute_query

Executes a potentially destructive SQL query (INSERT, UPDATE, DELETE, CREATE, etc.) against a database.

describe_table

Gets schema information for a table.

vector_search

Performs vector similarity search using SQLite vector extensions.