Content
# 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.
<a href="https://glama.ai/mcp/servers/hnkzlqoh92">
<img width="380" height="200" src="https://glama.ai/mcp/servers/hnkzlqoh92/badge" alt="mcp-turso-cloud MCP server" />
</a>
## 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:
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: None
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.
Parameters:
- `database` (string, required): Database name
- `expiration` (string, optional): Token expiration time
- `permission` (string, optional): Permission level ('full-access' or
'read-only')
Example:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```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): 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:
```json
{
"table": "embeddings",
"vector_column": "embedding",
"query_vector": [0.1, 0.2, 0.3, 0.4],
"limit": 5,
"database": "vector_db"
}
```
## Development
### Setup
1. Clone the repository
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Run in development mode:
```bash
npm run dev
```
### Publishing
1. Update version in package.json
2. Build the project:
```bash
npm run build
```
3. Publish to npm:
```bash
npm publish
```
## 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)
