Skip to main content
Glama
Sign In
deenesjakoruzh

mcp-turso-cloud

by spences10
npmGitHub
TypeScript
MIT License
87
4
  • Linux
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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 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 and PRAGMA queries (safe, read-only operations)
  • Use execute_query for INSERT, UPDATE, DELETE, CREATE, DROP, and other operations that modify data

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:

{ "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_read_only_query

Executes a read-only SQL query (SELECT, PRAGMA) against a database.

Parameters:

  • query (string, required): SQL query to execute (must be SELECT or PRAGMA)
  • 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" }
execute_query

Executes a potentially destructive SQL query (INSERT, UPDATE, DELETE, CREATE, etc.) against a database.

Parameters:

  • query (string, required): SQL query to execute (cannot be SELECT or PRAGMA)
  • params (object, optional): Query parameters
  • database (string, optional): Database name (uses context if not provided)

Example:

{ "query": "INSERT INTO users (name, age) VALUES (?, ?)", "params": { "1": "Alice", "2": 30 }, "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" }

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

  1. Clone the repository
  2. Install dependencies:
npm install
  1. Build the project:
npm run build
  1. Run in development mode:
npm run dev

Publishing

  1. Update version in package.json
  2. Build the project:
npm run build
  1. Publish to npm:
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 file for details.

Acknowledgments

Built on:

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

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.

Tools

🗂️ 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.

  1. Features
    1. 🏢 Organization-Level Operations
    2. 💾 Database-Level Operations
  2. ⚠️ IMPORTANT: Query Execution Security ⚠️
    1. Two-Level Authentication System
      1. Configuration
        1. Cline/Claude Desktop Configuration
        2. Claude Desktop with WSL Configuration
        3. Environment Variables
      2. API
        1. Organization Tools
        2. Database Tools
      3. Development
        1. Setup
        2. Publishing
      4. Troubleshooting
        1. API Token Issues
        2. Database Connection Issues
      5. Contributing
        1. License
          1. Acknowledgments

            Related Resources

            Related MCP Servers

            • SQLite MCP Server

              modelcontextprotocol
              A
              security
              A
              license
              A
              quality
              A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through SQLite. This server enables running SQL queries, analyzing business data, and automatically generating business insight memos.
              Last updated -
              6
              44,650
              JavaScript
              MIT License

            • MongoDB

              QuantGeekDev
              -
              security
              A
              license
              -
              quality
              A Model Context Protocol (MCP) server that enables LLMs to interact directly with MongoDB databases. Query collections, inspect schemas, and manage data seamlessly through natural language.
              Last updated -
              340
              75
              TypeScript
              MIT License
              • Apple

            • mcp-lancedb

              adiom-data
              -
              security
              A
              license
              -
              quality
              A Model Context Protocol (MCP) server that enables LLMs to interact directly the documents that they have on-disk through agentic RAG and hybrid search in LanceDB. Ask LLMs questions about the dataset as a whole or about specific documents.
              Last updated -
              12
              31
              TypeScript
              MIT License
              • Apple

            • MCP Postgres Server

              MadeByNando
              -
              security
              F
              license
              -
              quality
              A server implementing the Model Context Protocol (MCP) for Cursor that allows using a PostgreSQL database as storage for model contexts, enabling secure database exploration and querying.
              Last updated -
              JavaScript
              • Linux
              • Apple

            View all related MCP servers

            New MCP Servers

            ID: hnkzlqoh92