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

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 specific databases

💾 Database-Level Operations

List Tables: View all tables in a specific database
Execute Query: Run SQL queries against your databases
Describe Table: Get schema information for database tables
Vector Search: Perform vector similarity search using SQLite vector extensions

Two-Level Authentication System

The server implements a sophisticated authentication system:

Organization-Level Authentication
- Uses a Turso Platform API token
- Manages databases and organization-level operations
- Obtained through the Turso dashboard
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

For WSL environments, add this to your Claude Desktop configuration:

{
	"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"
			]
		}
	}
}

Environment Variables

The server requires the following environment variables:

TURSO_API_TOKEN: Your Turso Platform API token (required)
TURSO_ORGANIZATION: Your Turso organization name (required)
TURSO_DEFAULT_DATABASE: Default database to use 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')

API

The server implements MCP Tools organized by category:

Organization Tools

list_databases

Lists all databases in your Turso organization.

Parameters: None

Example response:

{
	"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"
		}
	]
}

create_database

Creates a new database in your organization.

Parameters:

name (string, required): Name for the new database
group (string, optional): Group to assign the database to
regions (string[], optional): Regions to deploy the database to

Example:

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

delete_database

Deletes a database from your organization.

Parameters:

name (string, required): Name of the database to delete

Example:

{
	"name": "test_db"
}

generate_database_token

Generates a new token for a specific database.

Parameters:

database (string, required): Database name
expiration (string, optional): Token expiration time
permission (string, optional): Permission level ('full-access' or 'read-only')

Example:

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

Database Tools

list_tables

Lists all tables in a database.

Parameters:

database (string, optional): Database name (uses context if not provided)

Example:

{
	"database": "customer_db"
}

execute_query

Executes a SQL query against a database.

Parameters:

query (string, required): SQL query to execute
params (object, optional): Query parameters
database (string, optional): Database name (uses context if not provided)

Example:

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

describe_table

Gets schema information for a table.

Parameters:

table (string, required): Table name
database (string, optional): Database name (uses context if not provided)

Example:

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

vector_search

Performs vector similarity search using SQLite vector extensions.

Parameters:

table (string, required): Table name
vector_column (string, required): Column containing vectors
query_vector (number[], required): Query vector for similarity search
limit (number, optional): Maximum number of results (default: 10)
database (string, optional): Database name (uses context if not provided)

Example:

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

Development

Setup

Clone the repository
Install dependencies:

npm install

Build the project:

npm run build

Run in development mode:

npm run dev

Publishing

Update version in package.json
Build the project:

npm run build

Publish to npm:

npm publish

Troubleshooting

API Token Issues

If you encounter authentication errors:

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Acknowledgments

Built on: