mcp-turso-cloud
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Integrations
Enables vector similarity searches using SQLite vector extensions, allowing for querying vector data stored in Turso databases with customizable parameters.
Provides tools for managing Turso databases at both organization and database levels, including listing, creating, and deleting databases, generating authentication tokens, listing tables, executing SQL queries, describing table schemas, and performing vector similarity searches.
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:
Claude Desktop with WSL Configuration
For WSL environments, add this to your Claude Desktop configuration:
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:
create_database
Creates a new database in your organization.
Parameters:
name
(string, required): Name for the new databasegroup
(string, optional): Group to assign the database toregions
(string[], optional): Regions to deploy the database to
Example:
delete_database
Deletes a database from your organization.
Parameters:
name
(string, required): Name of the database to delete
Example:
generate_database_token
Generates a new token for a specific database.
Parameters:
database
(string, required): Database nameexpiration
(string, optional): Token expiration timepermission
(string, optional): Permission level ('full-access' or 'read-only')
Example:
Database Tools
list_tables
Lists all tables in a database.
Parameters:
database
(string, optional): Database name (uses context if not provided)
Example:
execute_query
Executes a SQL query against a database.
Parameters:
query
(string, required): SQL query to executeparams
(object, optional): Query parametersdatabase
(string, optional): Database name (uses context if not provided)
Example:
describe_table
Gets schema information for a table.
Parameters:
table
(string, required): Table namedatabase
(string, optional): Database name (uses context if not provided)
Example:
vector_search
Performs vector similarity search using SQLite vector extensions.
Parameters:
table
(string, required): Table namevector_column
(string, required): Column containing vectorsquery_vector
(number[], required): Query vector for similarity searchlimit
(number, optional): Maximum number of results (default: 10)database
(string, optional): Database name (uses context if not provided)
Example:
Development
Setup
- Clone the repository
- Install dependencies:
- Build the project:
- Run in development mode:
Publishing
- Update version in package.json
- Build the project:
- Publish to npm:
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:
You must be authenticated.
🗂️ 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
- Two-Level Authentication System
- Configuration
- API
- Development
- Troubleshooting
- Contributing
- License
- Acknowledgments