{
  "markdown": "# mcp-turso-cloud\n\nA Model Context Protocol (MCP) server that provides integration with\nTurso databases for LLMs. This server implements a two-level\nauthentication system to handle both organization-level and\ndatabase-level operations, making it easy to manage and query Turso\ndatabases directly from LLMs.\n\n<a href=\"https://glama.ai/mcp/servers/hnkzlqoh92\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/hnkzlqoh92/badge\" alt=\"mcp-turso-cloud MCP server\" />\n</a>\n\n## Features\n\n### 🏢 Organization-Level Operations\n\n- **List Databases**: View all databases in your Turso organization\n- **Create Database**: Create new databases with customizable options\n- **Delete Database**: Remove databases from your organization\n- **Generate Database Token**: Create authentication tokens for\n  specific databases\n\n### 💾 Database-Level Operations\n\n- **List Tables**: View all tables in a specific database\n- **Execute Read-Only Query**: Run SELECT and PRAGMA queries\n  (read-only operations)\n- **Execute Query**: Run potentially destructive SQL queries (INSERT,\n  UPDATE, DELETE, etc.)\n- **Describe Table**: Get schema information for database tables\n- **Vector Search**: Perform vector similarity search using SQLite\n  vector extensions\n\n## ⚠️ IMPORTANT: Query Execution Security ⚠️\n\nThis server implements a security-focused separation between read-only\nand destructive database operations:\n\n- Use `execute_read_only_query` for SELECT and PRAGMA queries (safe,\n  read-only operations)\n- Use `execute_query` for INSERT, UPDATE, DELETE, CREATE, DROP, and\n  other operations that modify data\n\nThis separation allows for different permission levels and approval\nrequirements:\n\n- Read-only operations can be auto-approved in many contexts\n- Destructive operations can require explicit approval for safety\n\n**ALWAYS CAREFULLY READ AND REVIEW SQL QUERIES BEFORE APPROVING\nTHEM!** This is especially critical for destructive operations that\ncan modify or delete data. Take time to understand what each query\ndoes before allowing it to execute.\n\n## Two-Level Authentication System\n\nThe server implements a sophisticated authentication system:\n\n1. **Organization-Level Authentication**\n\n   - Uses a Turso Platform API token\n   - Manages databases and organization-level operations\n   - Obtained through the Turso dashboard\n\n2. **Database-Level Authentication**\n   - Uses database-specific tokens\n   - Generated automatically using the organization token\n   - Cached for performance and rotated as needed\n\n## Configuration\n\nThis server requires configuration through your MCP client. Here are\nexamples for different environments:\n\n### Cline/Claude Desktop Configuration\n\nAdd this to your Cline/Claude Desktop MCP settings:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"mcp-turso-cloud\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"mcp-turso-cloud\"],\n\t\t\t\"env\": {\n\t\t\t\t\"TURSO_API_TOKEN\": \"your-turso-api-token\",\n\t\t\t\t\"TURSO_ORGANIZATION\": \"your-organization-name\",\n\t\t\t\t\"TURSO_DEFAULT_DATABASE\": \"optional-default-database\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### Claude Desktop with WSL Configuration\n\nFor WSL environments, add this to your Claude Desktop configuration:\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"mcp-turso-cloud\": {\n\t\t\t\"command\": \"wsl.exe\",\n\t\t\t\"args\": [\n\t\t\t\t\"bash\",\n\t\t\t\t\"-c\",\n\t\t\t\t\"TURSO_API_TOKEN=your-token TURSO_ORGANIZATION=your-org node /path/to/mcp-turso-cloud/dist/index.js\"\n\t\t\t]\n\t\t}\n\t}\n}\n```\n\n### Environment Variables\n\nThe server requires the following environment variables:\n\n- `TURSO_API_TOKEN`: Your Turso Platform API token (required)\n- `TURSO_ORGANIZATION`: Your Turso organization name (required)\n- `TURSO_DEFAULT_DATABASE`: Default database to use when none is\n  specified (optional)\n- `TOKEN_EXPIRATION`: Expiration time for generated database tokens\n  (optional, default: '7d')\n- `TOKEN_PERMISSION`: Permission level for generated tokens (optional,\n  default: 'full-access')\n\n## API\n\nThe server implements MCP Tools organized by category:\n\n### Organization Tools\n\n#### list_databases\n\nLists all databases in your Turso organization.\n\nParameters: None\n\nExample response:\n\n```json\n{\n\t\"databases\": [\n\t\t{\n\t\t\t\"name\": \"customer_db\",\n\t\t\t\"id\": \"abc123\",\n\t\t\t\"region\": \"us-east\",\n\t\t\t\"created_at\": \"2023-01-15T12:00:00Z\"\n\t\t},\n\t\t{\n\t\t\t\"name\": \"product_db\",\n\t\t\t\"id\": \"def456\",\n\t\t\t\"region\": \"eu-west\",\n\t\t\t\"created_at\": \"2023-02-20T15:30:00Z\"\n\t\t}\n\t]\n}\n```\n\n#### create_database\n\nCreates a new database in your organization.\n\nParameters:\n\n- `name` (string, required): Name for the new database\n- `group` (string, optional): Group to assign the database to\n- `regions` (string[], optional): Regions to deploy the database to\n\nExample:\n\n```json\n{\n\t\"name\": \"analytics_db\",\n\t\"group\": \"production\",\n\t\"regions\": [\"us-east\", \"eu-west\"]\n}\n```\n\n#### delete_database\n\nDeletes a database from your organization.\n\nParameters:\n\n- `name` (string, required): Name of the database to delete\n\nExample:\n\n```json\n{\n\t\"name\": \"test_db\"\n}\n```\n\n#### generate_database_token\n\nGenerates a new token for a specific database.\n\nParameters:\n\n- `database` (string, required): Database name\n- `expiration` (string, optional): Token expiration time\n- `permission` (string, optional): Permission level ('full-access' or\n  'read-only')\n\nExample:\n\n```json\n{\n\t\"database\": \"customer_db\",\n\t\"expiration\": \"30d\",\n\t\"permission\": \"read-only\"\n}\n```\n\n### Database Tools\n\n#### list_tables\n\nLists all tables in a database.\n\nParameters:\n\n- `database` (string, optional): Database name (uses context if not\n  provided)\n\nExample:\n\n```json\n{\n\t\"database\": \"customer_db\"\n}\n```\n\n#### execute_read_only_query\n\nExecutes a read-only SQL query (SELECT, PRAGMA) against a database.\n\nParameters:\n\n- `query` (string, required): SQL query to execute (must be SELECT or\n  PRAGMA)\n- `params` (object, optional): Query parameters\n- `database` (string, optional): Database name (uses context if not\n  provided)\n\nExample:\n\n```json\n{\n\t\"query\": \"SELECT * FROM users WHERE age > ?\",\n\t\"params\": { \"1\": 21 },\n\t\"database\": \"customer_db\"\n}\n```\n\n#### execute_query\n\nExecutes a potentially destructive SQL query (INSERT, UPDATE, DELETE,\nCREATE, etc.) against a database.\n\nParameters:\n\n- `query` (string, required): SQL query to execute (cannot be SELECT\n  or PRAGMA)\n- `params` (object, optional): Query parameters\n- `database` (string, optional): Database name (uses context if not\n  provided)\n\nExample:\n\n```json\n{\n\t\"query\": \"INSERT INTO users (name, age) VALUES (?, ?)\",\n\t\"params\": { \"1\": \"Alice\", \"2\": 30 },\n\t\"database\": \"customer_db\"\n}\n```\n\n#### describe_table\n\nGets schema information for a table.\n\nParameters:\n\n- `table` (string, required): Table name\n- `database` (string, optional): Database name (uses context if not\n  provided)\n\nExample:\n\n```json\n{\n\t\"table\": \"users\",\n\t\"database\": \"customer_db\"\n}\n```\n\n#### vector_search\n\nPerforms vector similarity search using SQLite vector extensions.\n\nParameters:\n\n- `table` (string, required): Table name\n- `vector_column` (string, required): Column containing vectors\n- `query_vector` (number[], required): Query vector for similarity\n  search\n- `limit` (number, optional): Maximum number of results (default: 10)\n- `database` (string, optional): Database name (uses context if not\n  provided)\n\nExample:\n\n```json\n{\n\t\"table\": \"embeddings\",\n\t\"vector_column\": \"embedding\",\n\t\"query_vector\": [0.1, 0.2, 0.3, 0.4],\n\t\"limit\": 5,\n\t\"database\": \"vector_db\"\n}\n```\n\n## Development\n\n### Setup\n\n1. Clone the repository\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Build the project:\n\n```bash\nnpm run build\n```\n\n4. Run in development mode:\n\n```bash\nnpm run dev\n```\n\n### Publishing\n\n1. Update version in package.json\n2. Build the project:\n\n```bash\nnpm run build\n```\n\n3. Publish to npm:\n\n```bash\nnpm publish\n```\n\n## Troubleshooting\n\n### API Token Issues\n\nIf you encounter authentication errors:\n\n1. Verify your Turso API token is valid and has the necessary\n   permissions\n2. Check that your organization name is correct\n3. Ensure your token hasn't expired\n\n### Database Connection Issues\n\nIf you have trouble connecting to databases:\n\n1. Verify the database exists in your organization\n2. Check that your API token has access to the database\n3. Ensure the database name is spelled correctly\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nBuilt on:\n\n- [Model Context Protocol](https://github.com/modelcontextprotocol)\n- [Turso Database](https://turso.tech)\n- [libSQL](https://github.com/libsql/libsql)\n",
  "bytes": 8470,
  "sha": "57bb6ea75e21dd2be6c2caf806b172700f931c780e591d040d38c09b746cbfa2",
  "repo_slug": "spences10/mcp-turso-cloud",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_spences10_mcp_turso_cloud_6406a691/readme"
}