Turso Cloud

Integra con bases de datos Turso para LLMs, con un sistema de autenticación de dos niveles para operaciones seguras.

GitHub
18
Prueba este MCPPatrocinado

Documentación

mcp-turso-cloud

Un servidor de Model Context Protocol (MCP) que proporciona integración con bases de datos Turso para LLMs. Este servidor implementa un sistema de autenticación de dos niveles para manejar operaciones tanto a nivel de organización como a nivel de base de datos, facilitando la gestión y consulta de bases de datos Turso directamente desde LLMs.

mcp-turso-cloud MCP server

Características

🏢 Operaciones a Nivel de Organización

  • Listar Bases de Datos: Ver todas las bases de datos en tu organización Turso
  • Crear Base de Datos: Crear nuevas bases de datos con opciones personalizables
  • Eliminar Base de Datos: Eliminar bases de datos de tu organización
  • Generar Token de Base de Datos: Crear tokens de autenticación para bases de datos específicas

💾 Operaciones a Nivel de Base de Datos

  • Listar Tablas: Ver todas las tablas en una base de datos específica
  • Ejecutar Consulta de Solo Lectura: Ejecutar consultas SELECT y PRAGMA (operaciones de solo lectura)
  • Ejecutar Consulta: Ejecutar consultas SQL potencialmente destructivas (INSERT, UPDATE, DELETE, etc.)
  • Describir Tabla: Obtener información del esquema para tablas de bases de datos
  • Búsqueda Vectorial: Realizar búsqueda de similitud vectorial usando extensiones vectoriales de SQLite

⚠️ IMPORTANTE: Seguridad en la Ejecución de Consultas ⚠️

Este servidor implementa una separación centrada en la seguridad entre operaciones de base de datos de solo lectura y destructivas:

  • Usa execute_read_only_query para SELECT, WITH/VALUES de solo lectura, EXPLAIN de lecturas, y PRAGMAs de metadatos en lista permitida.
  • Usa execute_query para INSERT, UPDATE, DELETE, CREATE, DROP, PRAGMAs de mutación, y otras operaciones que modifican datos.

Las herramientas de lectura siempre solicitan credenciales de solo lectura de Turso, incluso cuando ya hay clientes de acceso completo en caché. El endpoint de token recibe authorization=read-only como parámetro de consulta. Los fallos de lectura nunca recurren al acceso completo. Los tokens y clientes se almacenan en caché por separado según el permiso y se renuevan cuando los tokens expiran.

La validación SQL local rechaza múltiples declaraciones, PRAGMAs de mutación en la ruta de lectura, y funciones de archivo/extensión. Es una verificación de enrutamiento conservadora, no un analizador SQL completo ni un sustituto de la autorización del lado del servidor de Turso. Los nombres de PRAGMA desconocidos o entre comillas requieren la herramienta de escritura. Las declaraciones compuestas que contienen puntos y comas internos (como definiciones de disparadores) no son compatibles. Los identificadores en SQL generado se citan; los valores de datos usan enlaces.

Esta separación permite diferentes niveles de permiso y requisitos de aprobación:

  • Las operaciones de solo lectura pueden aprobarse automáticamente en muchos contextos
  • Las operaciones destructivas pueden requerir aprobación explícita por seguridad

¡SIEMPRE LEE Y REVISA CUIDADOSAMENTE LAS CONSULTAS SQL ANTES DE APROBARLAS! Esto es especialmente crítico para operaciones destructivas que pueden modificar o eliminar datos. Tómate el tiempo para entender qué hace cada consulta antes de permitir que se ejecute.

Sistema de Autenticación de Dos Niveles

El servidor implementa un sistema de autenticación sofisticado:

  1. Autenticación a Nivel de Organización

    • Usa un token de API de la Plataforma Turso
    • Gestiona bases de datos y operaciones a nivel de organización
    • Se obtiene a través del panel de control de Turso

  2. Autenticación a Nivel de Base de Datos

    • Usa tokens específicos de la base de datos
    • Se generan automáticamente usando el token de organización
    • Se almacenan en caché por rendimiento y se rotan según sea necesario

Configuración

Este servidor requiere configuración a través de tu cliente MCP. Aquí hay ejemplos para diferentes entornos:

Configuración de Cline/Claude Desktop

Añade esto a tu configuración MCP de Cline/Claude Desktop:

{
	"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 con Configuración WSL

Para entornos WSL, añade esto a tu configuración de Claude Desktop:

{
	"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"
			]
		}
	}
}

Variables de Entorno

El servidor requiere las siguientes variables de entorno:

  • TURSO_API_TOKEN: Tu token de API de la Plataforma Turso (requerido)
  • TURSO_ORGANIZATION: El nombre de tu organización Turso (requerido)
  • TURSO_DEFAULT_DATABASE: Base de datos predeterminada a usar cuando no se especifica ninguna (opcional)
  • TOKEN_EXPIRATION: Tiempo de expiración para tokens de base de datos generados (opcional, predeterminado: '7d')
  • TOKEN_PERMISSION: Nivel de permiso para tokens generados (opcional, predeterminado: 'full-access')

API

El servidor implementa Herramientas MCP organizadas por categoría:

Herramientas de Organización

list_databases

Lista todas las bases de datos en tu organización Turso.

Parámetros:

  • limit (entero, opcional): Resultados máximos, predeterminado 1000, máximo 10000
  • offset (entero, opcional): Resultados a omitir, predeterminado 0, máximo 1000000

Las respuestas incluyen pagination con returned_count, has_more, y next_offset.

Ejemplo de respuesta:

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

Crea una nueva base de datos en tu organización.

Parámetros:

  • name (cadena, requerido): Nombre para la nueva base de datos
  • group (cadena, opcional): Grupo al que asignar la base de datos
  • regions (cadena[], opcional): Regiones donde implementar la base de datos

Ejemplo:

{
	"name": "analytics_db",
	"group": "production",
	"regions": ["us-east", "eu-west"]
}

delete_database

Elimina una base de datos de tu organización.

Parámetros:

  • name (cadena, requerido): Nombre de la base de datos a eliminar

Ejemplo:

{
	"name": "test_db"
}

generate_database_token

Genera un nuevo token para una base de datos específica. La expiración se configura a través de TOKEN_EXPIRATION; el JWT devuelto es un secreto.

Parámetros:

  • database (cadena, requerido): Nombre de la base de datos
  • permission (cadena, opcional): Nivel de permiso ('full-access' o 'read-only')

Ejemplo:

{
	"database": "customer_db",
	"permission": "read-only"
}

Herramientas de Base de Datos

Los nombres de bases de datos se limitan a 1–64 letras, dígitos, guiones bajos o guiones. Los identificadores de tabla/columna aceptan 1–64 caracteres, excluyendo bytes nulos; la puntuación y las comillas se escapan de forma segura. Una base de datos proporcionada se convierte en el contexto actual solo después de que su operación tenga éxito.

list_tables

Lista todas las tablas en una base de datos, con metadatos de paginación.

Parámetros:

  • database (cadena, opcional): Nombre de la base de datos (usa el contexto si no se proporciona)
  • limit (entero, opcional): Resultados máximos, predeterminado 1000, máximo 10000
  • offset (entero, opcional): Resultados a omitir, predeterminado 0, máximo 1000000

Ejemplo:

{
	"database": "customer_db"
}

execute_read_only_query

Ejecuta una consulta SELECT, WITH/VALUES de solo lectura, EXPLAIN de una lectura, o PRAGMA de metadatos en lista permitida contra una base de datos.

Parámetros:

  • query (cadena, requerido): Una declaración SQL, máximo 10000 caracteres
  • params (objeto, opcional): Parámetros nombrados o claves posicionales contiguas que comienzan en "1"; los valores deben ser cadenas, números finitos, booleanos o nulos
  • database (cadena, opcional): Nombre de la base de datos (usa el contexto si no se proporciona)
  • limit (entero, opcional): Filas máximas, predeterminado 1000, máximo 10000
  • offset (entero, opcional): Filas a omitir, predeterminado 0, máximo 1000000

Las consultas de estilo SELECT se envuelven con un límite/desplazamiento externo, preservando cualquier límite ya presente en tu SQL. Los resultados de PRAGMA de metadatos y EXPLAIN se dividen después de la obtención. Usa un ORDER BY estable al paginar. Las respuestas conservan result.rows y añaden metadatos pagination.

Las filas de resultados de consulta y los nombres de columnas tienen un presupuesto JSON de 512 KiB. Si una fila no cabe, selecciona menos columnas o columnas más pequeñas (por ejemplo, substr). result.truncated y truncation_reason explican los resultados omitidos; next_offset es nulo cuando ninguna fila cabe. Los BigInt son cadenas decimales y los blobs son { "type": "blob", "base64": "..." }.

Ejemplo:

{
	"query": "SELECT * FROM users WHERE age > ?",
	"params": { "1": 21 },
	"database": "customer_db"
}

execute_query

Ejecuta una consulta SQL potencialmente destructiva (INSERT, UPDATE, DELETE, CREATE, etc.) contra una base de datos.

Parámetros:

  • query (cadena, requerido): Una declaración de escritura, máximo 10000 caracteres; incluye PRAGMAs de mutación y escrituras con prefijo WITH
  • params (objeto, opcional): Mismos tipos de parámetros que la herramienta de lectura
  • database (cadena, opcional): Nombre de la base de datos (usa el contexto si no se proporciona)

Ejemplo:

{
	"query": "INSERT INTO users (name, age) VALUES (?, ?)",
	"params": { "1": "Alice", "2": 30 },
	"database": "customer_db"
}

Las filas de resultados de escritura (como RETURNING) están limitadas a 1000 filas y al mismo presupuesto de bytes. rowsAffected permanece intacto. La truncación no deshace la escritura: no vuelvas a ejecutar una escritura para obtener filas omitidas.

describe_table

Obtiene información del esquema para una tabla.

Parámetros:

  • table (cadena, requerido): Nombre de la tabla
  • database (cadena, opcional): Nombre de la base de datos (usa el contexto si no se proporciona)

Ejemplo:

{
	"table": "users",
	"database": "customer_db"
}

vector_search

Realiza búsqueda de similitud vectorial usando extensiones vectoriales de SQLite.

Parámetros:

  • table (cadena, requerido): Nombre de la tabla
  • vector_column (cadena, requerido): Columna que contiene vectores
  • query_vector (número[], requerido): 1–4096 números finitos
  • limit (entero, opcional): Resultados máximos, predeterminado 10, máximo 1000
  • database (cadena, opcional): Nombre de la base de datos (usa el contexto si no se proporciona)

Ejemplo:

{
	"table": "embeddings",
	"vector_column": "embedding",
	"query_vector": [0.1, 0.2, 0.3, 0.4],
	"limit": 5,
	"database": "vector_db"
}

Desarrollo

Configuración

Usa Node.js 24.15.0 o más reciente y pnpm 12.5.1 (fijado en package.json). .node-version selecciona el entorno de ejecución de desarrollo.

pnpm install
pnpm check
pnpm test

Vite+ proporciona la compilación, formato, linting, verificación de tipos y ejecutor de pruebas a través de vite.config.ts:

  • pnpm build — agrupa el ejecutable y las declaraciones en dist/
  • pnpm start — ejecuta el servidor compilado con tu configuración de Turso
  • pnpm dev — recompila ante cambios en el código fuente
  • pnpm inspect — abre el inspector MCP contra el servidor compilado
  • pnpm check — verifica formato, lint y tipos
  • pnpm check:fix — aplica formato y correcciones de lint seguras
  • pnpm format / pnpm format:check — formatea o verifica el formato
  • pnpm test — compila y ejecuta pruebas offline de SQL, permisos, tokens, manejadores MCP y CLI; no se necesitan credenciales de Turso ni acceso a bases de datos en vivo. Las pruebas de ejecución SQL usan una base de datos libSQL aislada en memoria.

Las versiones de dependencias viven en el catálogo pnpm-workspace.yaml. Las nuevas versiones deben tener al menos dos días de antigüedad antes de instalarse.

Editores

Instala la extensión Oxc en Zed o el Vite Plus Extension Pack en VS Code. Los .zed/settings.json y .vscode/settings.json incluidos usan Oxfmt con la configuración de formato compartida vite.config.ts. La configuración de Prettier ya no se usa.

Publicación

pnpm changeset
pnpm version
pnpm check
pnpm test
pnpm release

pnpm release compila y publica a través de Changesets. pnpm pack puede verificar el paquete localmente sin publicar.

Solución de Problemas

Problemas con el Token de API

Si encuentras errores de autenticación:

  1. Verifica que tu token de API de Turso sea válido y tenga los permisos necesarios
  2. Comprueba que el nombre de tu organización sea correcto
  3. Asegúrate de que tu token no haya expirado

Problemas de Conexión a la Base de Datos

Si tienes problemas para conectarte a las bases de datos:

  1. Verifica que la base de datos exista en tu organización
  2. Comprueba que tu token de API tenga acceso a la base de datos
  3. Asegúrate de que el nombre de la base de datos esté escrito correctamente

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción.

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

Agradecimientos

Construido sobre: