Turso Cloud

Integre com bancos de dados Turso para LLMs, com um sistema de autenticação de dois níveis para operações seguras.

GitHub
18
Experimente este MCPPatrocinado

Documentação

mcp-turso-cloud

Um servidor Model Context Protocol (MCP) que fornece integração com bancos de dados Turso para LLMs. Este servidor implementa um sistema de autenticação de dois níveis para lidar com operações tanto no nível da organização quanto no nível do banco de dados, facilitando o gerenciamento e a consulta de bancos de dados Turso diretamente a partir de LLMs.

mcp-turso-cloud MCP server

Recursos

🏢 Operações no Nível da Organização

  • Listar Bancos de Dados: Visualize todos os bancos de dados na sua organização Turso
  • Criar Banco de Dados: Crie novos bancos de dados com opções personalizáveis
  • Excluir Banco de Dados: Remova bancos de dados da sua organização
  • Gerar Token de Banco de Dados: Crie tokens de autenticação para bancos de dados específicos

💾 Operações no Nível do Banco de Dados

  • Listar Tabelas: Visualize todas as tabelas em um banco de dados específico
  • Executar Consulta Somente Leitura: Execute consultas SELECT e PRAGMA (operações somente leitura)
  • Executar Consulta: Execute consultas SQL potencialmente destrutivas (INSERT, UPDATE, DELETE, etc.)
  • Descrever Tabela: Obtenha informações de esquema para tabelas do banco de dados
  • Busca Vetorial: Realize busca por similaridade vetorial usando extensões vetoriais do SQLite

⚠️ IMPORTANTE: Segurança na Execução de Consultas ⚠️

Este servidor implementa uma separação focada em segurança entre operações de banco de dados somente leitura e destrutivas:

  • Use execute_read_only_query para SELECT, WITH/VALUES somente leitura, EXPLAIN de leituras e PRAGMAs de metadados na lista de permissões.
  • Use execute_query para INSERT, UPDATE, DELETE, CREATE, DROP, PRAGMAs de mutação e outras operações que modificam dados.

As ferramentas de leitura sempre solicitam credenciais Turso somente leitura, inclusive quando clientes com acesso total já estão em cache. O endpoint de token recebe authorization=read-only como parâmetro de consulta. Falhas de leitura nunca recorrem ao acesso total. Tokens e clientes são armazenados em cache separadamente por permissão e atualizados quando os tokens expiram.

A validação SQL local rejeita múltiplas instruções, PRAGMAs de mutação no caminho de leitura e funções de arquivo/extensão. É uma verificação de roteamento conservadora, não um parser SQL completo nem um substituto para a autorização do lado do servidor do Turso. Nomes de PRAGMA desconhecidos ou entre aspas exigem a ferramenta de escrita. Instruções compostas contendo ponto e vírgula internos (como definições de gatilhos) não são suportadas. Identificadores em SQL gerado são entre aspas; valores de dados usam bindings.

Essa separação permite diferentes níveis de permissão e requisitos de aprovação:

  • Operações somente leitura podem ser aprovadas automaticamente em muitos contextos
  • Operações destrutivas podem exigir aprovação explícita por segurança

SEMPRE LEIA E REVISE CUIDADOSAMENTE AS CONSULTAS SQL ANTES DE APROVÁ-LAS! Isso é especialmente crítico para operações destrutivas que podem modificar ou excluir dados. Reserve um tempo para entender o que cada consulta faz antes de permitir sua execução.

Sistema de Autenticação de Dois Níveis

O servidor implementa um sistema de autenticação sofisticado:

  1. Autenticação no Nível da Organização

    • Usa um token da API da Plataforma Turso
    • Gerencia bancos de dados e operações no nível da organização
    • Obtido através do painel da Turso

  2. Autenticação no Nível do Banco de Dados

    • Usa tokens específicos do banco de dados
    • Gerados automaticamente usando o token da organização
    • Armazenados em cache para desempenho e rotacionados conforme necessário

Configuração

Este servidor requer configuração através do seu cliente MCP. Aqui estão exemplos para diferentes ambientes:

Configuração Cline/Claude Desktop

Adicione isto às configurações MCP do seu 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"
			}
		}
	}
}

Configuração Claude Desktop com WSL

Para ambientes WSL, adicione isto à sua configuração do 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"
			]
		}
	}
}

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

  • TURSO_API_TOKEN: Seu token da API da Plataforma Turso (obrigatório)
  • TURSO_ORGANIZATION: O nome da sua organização Turso (obrigatório)
  • TURSO_DEFAULT_DATABASE: Banco de dados padrão a ser usado quando nenhum for especificado (opcional)
  • TOKEN_EXPIRATION: Tempo de expiração para tokens de banco de dados gerados (opcional, padrão: '7d')
  • TOKEN_PERMISSION: Nível de permissão para tokens gerados (opcional, padrão: 'full-access')

API

O servidor implementa Ferramentas MCP organizadas por categoria:

Ferramentas da Organização

list_databases

Lista todos os bancos de dados na sua organização Turso.

Parâmetros:

  • limit (inteiro, opcional): Resultados máximos, padrão 1000, máximo 10000
  • offset (inteiro, opcional): Resultados a pular, padrão 0, máximo 1000000

As respostas incluem pagination com returned_count, has_more e next_offset.

Exemplo de resposta:

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

Cria um novo banco de dados na sua organização.

Parâmetros:

  • name (string, obrigatório): Nome para o novo banco de dados
  • group (string, opcional): Grupo ao qual atribuir o banco de dados
  • regions (string[], opcional): Regiões para implantar o banco de dados

Exemplo:

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

delete_database

Exclui um banco de dados da sua organização.

Parâmetros:

  • name (string, obrigatório): Nome do banco de dados a ser excluído

Exemplo:

{
	"name": "test_db"
}

generate_database_token

Gera um novo token para um banco de dados específico. A expiração é configurada através de TOKEN_EXPIRATION; o JWT retornado é um segredo.

Parâmetros:

  • database (string, obrigatório): Nome do banco de dados
  • permission (string, opcional): Nível de permissão ('full-access' ou 'read-only')

Exemplo:

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

Ferramentas do Banco de Dados

Os nomes dos bancos de dados são limitados a 1–64 letras, dígitos, sublinhados ou hífens. Identificadores de tabela/coluna aceitam 1–64 caracteres, excluindo bytes nulos; pontuação e aspas são escapadas com segurança. Um banco de dados fornecido torna-se o contexto atual somente após sua operação ser bem-sucedida.

list_tables

Lista todas as tabelas em um banco de dados, com metadados de paginação.

Parâmetros:

  • database (string, opcional): Nome do banco de dados (usa o contexto se não fornecido)
  • limit (inteiro, opcional): Resultados máximos, padrão 1000, máximo 10000
  • offset (inteiro, opcional): Resultados a pular, padrão 0, máximo 1000000

Exemplo:

{
	"database": "customer_db"
}

execute_read_only_query

Executa uma consulta SELECT, WITH/VALUES somente leitura, EXPLAIN de uma leitura ou PRAGMA de metadados na lista de permissões contra um banco de dados.

Parâmetros:

  • query (string, obrigatório): Uma instrução SQL, máximo 10000 caracteres
  • params (objeto, opcional): Parâmetros nomeados ou chaves posicionais contíguas começando em "1"; valores devem ser strings, números finitos, booleanos ou null
  • database (string, opcional): Nome do banco de dados (usa o contexto se não fornecido)
  • limit (inteiro, opcional): Linhas máximas, padrão 1000, máximo 10000
  • offset (inteiro, opcional): Linhas a pular, padrão 0, máximo 1000000

Consultas estilo SELECT são envolvidas com um limite/deslocamento externo, preservando qualquer limite já presente no seu SQL. Resultados de PRAGMA de metadados e EXPLAIN são fatiados após a busca. Use um ORDER BY estável ao paginar. As respostas retêm result.rows e adicionam metadados pagination.

Linhas de resultados de consulta e nomes de colunas têm um orçamento JSON de 512 KiB. Se uma linha não couber, selecione menos colunas ou colunas menores (por exemplo, substr). result.truncated e truncation_reason explicam resultados omitidos; next_offset é null quando nenhuma linha cabe. BigInts são strings decimais e blobs são { "type": "blob", "base64": "..." }.

Exemplo:

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

execute_query

Executa uma consulta SQL potencialmente destrutiva (INSERT, UPDATE, DELETE, CREATE, etc.) contra um banco de dados.

Parâmetros:

  • query (string, obrigatório): Uma instrução de escrita, máximo 10000 caracteres; inclui PRAGMAs de mutação e escritas prefixadas com WITH
  • params (objeto, opcional): Mesmos tipos de parâmetros da ferramenta de leitura
  • database (string, opcional): Nome do banco de dados (usa o contexto se não fornecido)

Exemplo:

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

Linhas de resultados de escrita (como RETURNING) são limitadas a 1000 linhas e ao mesmo orçamento de bytes. rowsAffected permanece intacto. A truncagem não desfaz a escrita: não execute novamente uma escrita para buscar linhas omitidas.

describe_table

Obtém informações de esquema para uma tabela.

Parâmetros:

  • table (string, obrigatório): Nome da tabela
  • database (string, opcional): Nome do banco de dados (usa o contexto se não fornecido)

Exemplo:

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

vector_search

Realiza busca por similaridade vetorial usando extensões vetoriais do SQLite.

Parâmetros:

  • table (string, obrigatório): Nome da tabela
  • vector_column (string, obrigatório): Coluna contendo vetores
  • query_vector (number[], obrigatório): 1–4096 números finitos
  • limit (inteiro, opcional): Resultados máximos, padrão 10, máximo 1000
  • database (string, opcional): Nome do banco de dados (usa o contexto se não fornecido)

Exemplo:

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

Desenvolvimento

Configuração

Use Node.js 24.15.0 ou mais recente e pnpm 12.5.1 (fixado em package.json). .node-version seleciona o runtime de desenvolvimento.

pnpm install
pnpm check
pnpm test

Vite+ fornece o build, formatação, lint, verificação de tipos e executor de testes através de vite.config.ts:

  • pnpm build — empacota o executável e as declarações em dist/
  • pnpm start — executa o servidor compilado com sua configuração Turso
  • pnpm dev — recompila em mudanças de código-fonte
  • pnpm inspect — abre o inspetor MCP contra o servidor compilado
  • pnpm check — verifica formatação, lint e tipos
  • pnpm check:fix — aplica formatação e correções seguras de lint
  • pnpm format / pnpm format:check — formata ou verifica formatação
  • pnpm test — compila e executa testes offline de SQL, permissão, token, MCP handler e CLI; nenhuma credencial Turso ou acesso a banco de dados ao vivo necessário. Testes de execução SQL usam um banco de dados libSQL isolado em memória.

As versões das dependências estão no catálogo pnpm-workspace.yaml. Novos lançamentos devem ter pelo menos dois dias de idade antes da instalação.

Editores

Instale a extensão Oxc no Zed ou o Vite Plus Extension Pack no VS Code. .zed/settings.json e .vscode/settings.json verificados usam Oxfmt com as configurações de formatação compartilhadas vite.config.ts. A configuração do Prettier não é mais usada.

Publicação

pnpm changeset
pnpm version
pnpm check
pnpm test
pnpm release

pnpm release compila e publica através do Changesets. pnpm pack pode verificar o pacote localmente sem publicar.

Solução de Problemas

Problemas com Token da API

Se você encontrar erros de autenticação:

  1. Verifique se seu token da API Turso é válido e tem as permissões necessárias
  2. Verifique se o nome da sua organização está correto
  3. Garanta que seu token não expirou

Problemas de Conexão com o Banco de Dados

Se você tiver problemas para conectar aos bancos de dados:

  1. Verifique se o banco de dados existe na sua organização
  2. Verifique se seu token da API tem acesso ao banco de dados
  3. Garanta que o nome do banco de dados esteja escrito corretamente

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

Agradecimentos

Construído sobre: