Turso Cloud MCP server

mcp-turso-cloud

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.

Features

🏢 Organization-Level Operations

specific databases

• List Databases: View all databases in your Turso organization
• Create Database: Create new databases with customizable options
• Delete Database: Remove databases from your organization
• Generate Database Token: Create authentication tokens for

💾 Database-Level Operations

(read-only operations)

• List Tables: View all tables in a specific database
• Execute Read-Only Query: Run SELECT and PRAGMA queries

UPDATE, DELETE, etc.)

• Execute Query: Run potentially destructive SQL queries (INSERT,

vector extensions

• Describe Table: Get schema information for database tables
• Vector Search: Perform vector similarity search using SQLite

⚠️ IMPORTANT: Query Execution Security ⚠️

This server implements a security-focused separation between read-only and destructive database operations:

EXPLAIN of reads, and allowlisted metadata PRAGMAs.

• Use executereadonly_query for SELECT, read-only WITH/VALUES,

mutating PRAGMAs, and other operations that modify data.

• Use execute_query for INSERT, UPDATE, DELETE, CREATE, DROP,

Read tools always request read-only Turso credentials, including when full-access clients are already cached. The token endpoint receives authorization=read-only as a query parameter. Read failures never fall back to full access. Tokens and clients are cached separately by permission and refreshed when tokens expire.

Local SQL validation rejects multiple statements, mutating PRAGMAs on the read path, and file/extension functions. It is a conservative routing check, not a complete SQL parser or a substitute for Turso's server-side authorization. Unknown or quoted PRAGMA names require the write tool. Compound statements containing internal semicolons (such as trigger definitions) are not supported. Identifiers in generated SQL are quoted; data values use bindings.

This separation allows for different permission levels and approval requirements:

• Read-only operations can be auto-approved in many contexts
• Destructive operations can require explicit approval for safety

ALWAYS CAREFULLY READ AND REVIEW SQL QUERIES BEFORE APPROVING THEM! This is especially critical for destructive operations that can modify or delete data. Take time to understand what each query does before allowing it to execute.

Two-Level Authentication System

The server implements a sophisticated authentication system:

1. Organization-Level Authentication

• Uses a Turso Platform API token
• Manages databases and organization-level operations
• Obtained through the Turso dashboard

1. Database-Level Authentication

• Uses database-specific tokens
• Generated automatically using the organization token
• Cached for performance and rotated as needed

Configuration

This server requires configuration through your MCP client. Here are examples for different environments:

Cline/Claude Desktop Configuration

Add this to your Cline/Claude Desktop MCP settings:

{
	"mcpServers": {
		"mcp-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"
			}
		}
	}
}

Claude Desktop with WSL Configuration

Shortened. The full README is on GitHub.