# 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 Read-Only Query**: Run SELECT and PRAGMA queries (read-only operations) - **Execute Query**: Run potentially destructive SQL queries (INSERT, UPDATE, DELETE, etc.) - **Describe Table**: Get schema information for database tables - **Vector Search**: Perform vector similarity search using SQLite vector extensions ## ⚠️ IMPORTANT: Query Execution Security ⚠️ This server implements a security-focused separation between read-only and destructive database operations: - Use `execute_read_only_query` for SELECT, read-only WITH/VALUES, EXPLAIN of reads, and allowlisted metadata PRAGMAs. - Use `execute_query` for INSERT, UPDATE, DELETE, CREATE, DROP, mutating PRAGMAs, and other operations that modify data. Read tools always request read-only Turso credentials, including when full-access clients are already cached. The token endpoint receives [`authorization=read-only`](https://docs.turso.tech/api-reference/databases/create-token) 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 2. **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: ```json { "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: ```json { "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: - `limit` (integer, optional): Maximum results, default 1000, maximum 10000 - `offset` (integer, optional): Results to skip, default 0, maximum 1000000 Responses include `pagination` with `returned_count`, `has_more`, and `next_offset`. Example response: ```json { "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: ```json { "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: ```json { "name": "test_db" } ``` #### generate_database_token Generates a new token for a specific database. Expiration is configured through `TOKEN_EXPIRATION`; the returned JWT is a secret. Parameters: - `database` (string, required): Database name - `permission` (string, optional): Permission level ('full-access' or 'read-only') Example: ```json { "database": "customer_db", "permission": "read-only" } ``` ### Database Tools Database names are limited to 1–64 letters, digits, underscores, or hyphens. Table/column identifiers accept 1–64 characters, excluding null bytes; punctuation and quotes are safely escaped. A supplied database becomes the current context only after its operation succeeds. #### list_tables Lists all tables in a database, with pagination metadata. Parameters: - `database` (string, optional): Database name (uses context if not provided) - `limit` (integer, optional): Maximum results, default 1000, maximum 10000 - `offset` (integer, optional): Results to skip, default 0, maximum 1000000 Example: ```json { "database": "customer_db" } ``` #### execute_read_only_query Executes one SELECT, read-only WITH/VALUES query, EXPLAIN of a read, or allowlisted metadata PRAGMA against a database. Parameters: - `query` (string, required): One SQL statement, maximum 10000 characters - `params` (object, optional): Named parameters or contiguous positional keys starting at `"1"`; values must be strings, finite numbers, booleans, or null - `database` (string, optional): Database name (uses context if not provided) - `limit` (integer, optional): Maximum rows, default 1000, maximum 10000 - `offset` (integer, optional): Rows to skip, default 0, maximum 1000000 SELECT-style queries are wrapped with an outer limit/offset, preserving any limit already present in your SQL. Metadata PRAGMA and EXPLAIN results are sliced after fetching. Use a stable `ORDER BY` when paging. Responses retain `result.rows` and add `pagination` metadata. Query result rows and column names have a 512 KiB JSON budget. If a row cannot fit, select fewer/smaller columns (for example, `substr`). `result.truncated` and `truncation_reason` explain omitted results; `next_offset` is null when no row fits. BigInts are decimal strings and blobs are `{ "type": "blob", "base64": "..." }`. Example: ```json { "query": "SELECT * FROM users WHERE age > ?", "params": { "1": 21 }, "database": "customer_db" } ``` #### execute_query Executes a potentially destructive SQL query (INSERT, UPDATE, DELETE, CREATE, etc.) against a database. Parameters: - `query` (string, required): One write statement, maximum 10000 characters; includes mutating PRAGMAs and WITH-prefixed writes - `params` (object, optional): Same parameter types as the read tool - `database` (string, optional): Database name (uses context if not provided) Example: ```json { "query": "INSERT INTO users (name, age) VALUES (?, ?)", "params": { "1": "Alice", "2": 30 }, "database": "customer_db" } ``` Write result rows (such as `RETURNING`) are capped at 1000 rows and the same byte budget. `rowsAffected` remains intact. Truncation does not undo the write: do not rerun a write to fetch omitted rows. #### 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: ```json { "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): 1–4096 finite numbers - `limit` (integer, optional): Maximum results, default 10, maximum 1000 - `database` (string, optional): Database name (uses context if not provided) Example: ```json { "table": "embeddings", "vector_column": "embedding", "query_vector": [0.1, 0.2, 0.3, 0.4], "limit": 5, "database": "vector_db" } ``` ## Development ### Setup Use Node.js 24.15.0 or newer and pnpm 12.5.1 (pinned in `package.json`). `.node-version` selects the development runtime. ```bash pnpm install pnpm check pnpm test ``` Vite+ provides the build, formatting, linting, type checking, and test runner through `vite.config.ts`: - `pnpm build` — bundle the executable and declarations into `dist/` - `pnpm start` — run the built server with your Turso configuration - `pnpm dev` — rebuild on source changes - `pnpm inspect` — open the MCP inspector against the built server - `pnpm check` — check formatting, lint, and types - `pnpm check:fix` — apply formatting and safe lint fixes - `pnpm format` / `pnpm format:check` — format or check formatting - `pnpm test` — build and run offline SQL, permission, token, MCP handler, and CLI tests; no Turso credentials or live database access needed. SQL execution tests use an isolated in-memory libSQL database. Dependency versions live in the `pnpm-workspace.yaml` catalog. New releases must be at least two days old before installation. ### Editors Install the **Oxc** extension in Zed or the **Vite Plus Extension Pack** in VS Code. Checked-in `.zed/settings.json` and `.vscode/settings.json` use Oxfmt with the shared `vite.config.ts` formatting settings. Prettier configuration is no longer used. ### Publishing ```bash pnpm changeset pnpm version pnpm check pnpm test pnpm release ``` `pnpm release` builds and publishes through Changesets. `pnpm pack` can verify the package locally without publishing. ## Troubleshooting ### API Token Issues If you encounter authentication errors: 1. Verify your Turso API token is valid and has the necessary permissions 2. Check that your organization name is correct 3. Ensure your token hasn't expired ### Database Connection Issues If you have trouble connecting to databases: 1. Verify the database exists in your organization 2. Check that your API token has access to the database 3. 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](LICENSE) file for details. ## Acknowledgments Built on: - [Model Context Protocol](https://github.com/modelcontextprotocol) - [Turso Database](https://turso.tech) - [libSQL](https://github.com/libsql/libsql)