Turso SQLite MCP server

The MCP-Turso-Cloud server provides seamless integration between LLMs and Turso databases through the Model Context Protocol, implementing a two-level authentication system that handles both organization-level and database-level operations for secure and efficient database management.

Features Overview

Organization-Level Operations

• List all databases in your Turso organization
• Create new databases with custom options
• Delete databases from your organization
• Generate authentication tokens for specific databases

Database-Level Operations

• List tables in a specific database
• Execute read-only queries (SELECT and PRAGMA)
• Execute data-modifying queries (INSERT, UPDATE, DELETE, etc.)
• Retrieve schema information for database tables
• Perform vector similarity searches using SQLite vector extensions

Installation and Configuration

Prerequisites

• Turso account with API token
• Node.js environment

Setup with Cline/Claude Desktop

Add this configuration 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"
			}
		}
	}
}

Setup with Claude Desktop in WSL

For Windows Subsystem for Linux environments:

{
	"mcpServers": {
		"mcp-turso-cloud": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"TURSO_API_TOKEN=your-token TURSO_ORGANIZATION=your-org node /path/to/mcp-turso-cloud/dist/index.js"
			]
		}
	}
}

Required Environment Variables

• TURSO_API_TOKEN: Your Turso Platform API token (required)
• TURSO_ORGANIZATION: Your Turso organization name (required)
• TURSO_DEFAULT_DATABASE: Default database when none is specified (optional)
• TOKEN_EXPIRATION: Expiration time for generated database tokens (optional, default: '7d')
• TOKEN_PERMISSION: Permission level for generated tokens (optional, default: 'full-access')

Using the MCP Server

Organization-Level Operations

Listing Databases

Use this to view all databases in your Turso organization:

{
	"databases": []
}

Response example:

{
	"databases": [
		{
			"name": "customer_db",
			"id": "abc123",
			"region": "us-east",
			"created_at": "2023-01-15T12:00:00Z"
		},
		{
			"name": "product_db",
			"id": "def456",
			"region": "eu-west",
			"created_at": "2023-02-20T15:30:00Z"
		}
	]
}

Creating a Database

To create a new database:

{
	"name": "analytics_db",
	"group": "production",
	"regions": ["us-east", "eu-west"]
}

Deleting a Database

To remove a database:

{
	"name": "test_db"
}

Generating a Database Token

Create authentication tokens for specific databases:

{
	"database": "customer_db",
	"expiration": "30d",
	"permission": "read-only"
}

Database-Level Operations

Listing Tables

To view all tables in a database:

{
	"database": "customer_db"
}

Executing Read-Only Queries

For safe, read-only operations (SELECT and PRAGMA):

{
	"query": "SELECT * FROM users WHERE age > ?",
	"params": { "1": 21 },
	"database": "customer_db"
}

Executing Data-Modifying Queries

For operations that modify data (INSERT, UPDATE, DELETE, etc.):

{
	"query": "INSERT INTO users (name, age) VALUES (?, ?)",
	"params": { "1": "Alice", "2": 30 },
	"database": "customer_db"
}

Describing Table Schema

Get detailed information about a table's structure:

{
	"table": "users",
	"database": "customer_db"
}

Vector Search

Perform similarity searches using vector data:

{
	"table": "embeddings",
	"vector_column": "embedding",
	"query_vector": [0.1, 0.2, 0.3, 0.4],
	"limit": 5,
	"database": "vector_db"
}

Troubleshooting

API Token Issues

If you encounter authentication problems:

• Verify your Turso API token is valid and has the necessary permissions
• Check that your organization name is correct
• Ensure your token hasn't expired

Database Connection Issues

If you have trouble connecting to databases:

• Verify the database exists in your organization
• Check that your API token has access to the database
• Ensure the database name is spelled correctly

Security Considerations

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

• execute_read_only_query is for SELECT and PRAGMA queries (safe operations)
• execute_query is for INSERT, UPDATE, DELETE, CREATE, DROP, and other operations that modify data

Always carefully review SQL queries before approving them, especially for destructive operations that can modify or delete data.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.