MCP Turso
Allows interaction with Turso Cloud databases, providing tools for CRUD operations, schema management, and SQL query execution via MCP.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP TursoList all tables in my Turso database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Turso
Português
Sobre o Projeto
MCP Turso é a primeira solução completa para integrar bancos de dados Turso Cloud com o Model Context Protocol (MCP) no VSCode. Este projeto permite que o GitHub Copilot interaja diretamente com seus bancos Turso através de ferramentas MCP, facilitando operações CRUD e consultas SQL.
Por que este projeto existe?
Primeira solução MCP para Turso: Não existia nenhuma implementação disponível para VSCODE
Integração nativa com VSCode: Funciona perfeitamente com o GitHub Copilot
Fácil configuração: Setup simples para Windows
Ferramentas completas: Suporte a todas as operações básicas de banco de dados
Related MCP server: MCP-Turso
Arquitetura MCP
Como o MCP Funciona
O Model Context Protocol (MCP) é um protocolo aberto que permite aos Large Language Models (LLMs) se conectarem a ferramentas e dados externos de forma padronizada.
Componentes Principais:
Cliente MCP: Aplicação que usa o protocolo (ex: GitHub Copilot, Claude Desktop)
Servidor MCP: Programa que expõe ferramentas e recursos (este projeto)
Comunicação: Via stdio (stdin/stdout) usando JSON-RPC 2.0
Fluxo de Funcionamento:
Cliente MCP inicia o servidor
Servidor registra suas ferramentas via
ListToolsCliente pode chamar ferramentas via
CallToolServidor executa a operação e retorna resultado
Segurança:
Queries SELECT são validadas automaticamente
Operações de escrita usam prepared statements
Comunicação local via stdio (não expõe portas de rede)
Estrutura do Projeto
mcp-turso/
├── src/
│ └── index.ts # Servidor MCP principal
├── dist/ # Código compilado (gerado)
├── .env # Variáveis de ambiente (não versionado)
├── package.json # Dependências e scripts
├── tsconfig.json # Configuração TypeScript
└── README.md # Esta documentaçãoPré-requisitos
Node.js 18+ (compatível com as dependências)
Uma conta Turso Cloud com banco de dados ativo
VSCode com GitHub Copilot instalado
Instalação
Passo 1: Criar o projeto
# Criar pasta do projeto
mkdir mcp-turso
cd mcp-turso
# Inicializar projeto Node.js
npm init -yPasso 2: Instalar dependências
npm install @modelcontextprotocol/sdk @libsql/client dotenv
npm install -D typescript @types/node tsxPasso 3: Configurar TypeScript
Crie o arquivo tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}Passo 4: Criar o código do servidor
Crie a pasta src e o arquivo src/index.ts com o código fornecido no repositório.
Passo 5: Configurar package.json
Edite o package.json para incluir:
{
"name": "mcp-turso",
"version": "1.0.0",
"type": "module",
"bin": {
"mcp-turso": "./dist/index.js"
},
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts",
"start": "node dist/index.js"
},
"dependencies": {
"@libsql/client": "^0.14.0",
"@modelcontextprotocol/sdk": "^1.0.4",
"dotenv": "^16.4.5"
},
"devDependencies": {
"@types/node": "^22.10.2",
"tsx": "^4.19.2",
"typescript": "^5.7.2"
}
}Passo 6: Compilar o projeto
npm run buildIsso cria a pasta dist/ com o código JavaScript compilado.
Configuração
Variáveis de Ambiente
Crie um arquivo .env na raiz do projeto:
TURSO_DATABASE_URL=libsql://seu-banco.turso.io
TURSO_AUTH_TOKEN=seu-token-aquiPara obter o token:
turso auth tokenConfiguração no VSCode
Passo 1: Criar arquivo MCP
Na raiz do seu projeto (não do mcp-turso), crie .vscode/mcp.json:
{
"mcpServers": {
"turso-": {
"command": "node",
"args": ["C:/caminho/completo/mcp-turso/dist/index.js"],
"env": {
"TURSO_DATABASE_URL": "libsql://seu-banco.turso.io",
"TURSO_AUTH_TOKEN": "seu-token-aqui"
}
}
}
}Importante: Substitua C:/caminho/completo/ pelo caminho real onde você criou o projeto mcp-turso.
Passo 2: Reiniciar VSCode
Feche completamente o VSCode e reabra para carregar a configuração MCP.
Uso no GitHub Copilot
Abra o Copilot Chat (Ctrl + Shift + I) e teste os comandos:
Liste todas as tabelas do meu banco de timesMostre a estrutura da tabela jogadoresConte quantos jogadores estão confirmadosInsira um novo jogador: nome "Carlos", whatsapp "11987654321"Adicione uma coluna telefone do tipo TEXT na tabela jogadoresCrie um índice único no email dos usuáriosAdicione uma foreign key entre jogadores e timesFerramentas Disponíveis
Ferramenta | Descrição | Exemplo |
| Lista todas as tabelas |
|
| Mostra estrutura de uma tabela |
|
| Executa SELECT (somente leitura) |
|
| Insere dados |
|
| Atualiza dados |
|
| Deleta dados |
|
| Conta registros |
|
| Adiciona coluna a tabela |
|
| Executa comandos DDL |
|
| Cria índice |
|
| Adiciona constraint |
|
| Inicia transação |
|
| Confirma transação |
|
| Cancela transação |
|
API Reference
Esquemas Detalhados das Ferramentas
list_tables
Descrição: Lista todas as tabelas do banco de dados Parâmetros: Nenhum Retorno: Lista de nomes de tabelas
describe_table
Descrição: Mostra a estrutura completa de uma tabela Parâmetros:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela a ser descrita"
}
},
"required": ["table"]
}Retorno: Schema da tabela com colunas, tipos e constraints
execute_select
Descrição: Executa uma query SELECT (somente leitura) Parâmetros:
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Query SQL SELECT válida"
}
},
"required": ["query"]
}Validação: Query deve começar com "SELECT" (case insensitive) Retorno: Resultado da query em formato JSON
insert_data
Descrição: Insere um novo registro na tabela Parâmetros:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela"
},
"data": {
"type": "object",
"description": "Objeto com dados a inserir",
"additionalProperties": true
}
},
"required": ["table", "data"]
}Retorno: ID do registro inserido
update_data
Descrição: Atualiza registros existentes Parâmetros:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela"
},
"data": {
"type": "object",
"description": "Dados a atualizar",
"additionalProperties": true
},
"where": {
"type": "string",
"description": "Condição WHERE para identificar registros"
}
},
"required": ["table", "data", "where"]
}Retorno: Número de registros afetados
delete_data
Descrição: Remove registros da tabela Parâmetros:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela"
},
"where": {
"type": "string",
"description": "Condição WHERE para identificar registros"
}
},
"required": ["table", "where"]
}Retorno: Número de registros removidos
count_rows
Descrição: Conta registros em uma tabela Parâmetros:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela"
},
"where": {
"type": "string",
"description": "Condição WHERE opcional"
}
},
"required": ["table"]
}Retorno: Número total de registros
add_column
Descrição: Adiciona uma nova coluna a uma tabela existente Parâmetros:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela"
},
"column": {
"type": "string",
"description": "Nome da nova coluna"
},
"type": {
"type": "string",
"description": "Tipo de dados da coluna (ex: 'TEXT', 'INTEGER', 'REAL', 'BLOB')"
},
"nullable": {
"type": "boolean",
"description": "Se a coluna pode ser NULL (padrão: true)",
"default": true
},
"default_value": {
"type": "string",
"description": "Valor padrão da coluna (opcional)"
}
},
"required": ["table", "column", "type"]
}Retorno: Confirmação da adição da coluna
Desenvolvimento
Para desenvolvimento local:
npm run dev # Executa com tsx (hot reload)Troubleshooting
Erro "command not found"
Use caminho absoluto em
argsno.vscode/mcp.jsonExemplo:
C:/Users/Lucas Silva/projetos/mcp-turso/dist/index.js
Erro de permissão
No primeiro uso, o Copilot vai pedir permissão
Clique em "Allow" ou "Continue"
Ferramentas não aparecem
Verifique se
npm run buildfoi executadoReinicie o VSCode completamente
Confirme se o caminho no
.vscode/mcp.jsonestá corretoVerifique logs em Output → MCP
Erro de conexão com Turso
Confirme se
TURSO_DATABASE_URLeTURSO_AUTH_TOKENestão corretosExecute
turso auth tokenpara gerar um novo token se necessário
Scripts Disponíveis
npm run build: Compila TypeScriptnpm run dev: Executa em modo desenvolvimentonpm start: Executa versão compilada
Roadmap
Próximas Funcionalidades
Suporte a transações SQL
Queries complexas com JOIN
Backup e restore de bancos
Interface web opcional para administração
Suporte a múltiplos bancos Turso
Integração com outras ferramentas MCP
Melhorias Planejadas
Validação de schema mais rigorosa
Suporte a tipos de dados avançados
Cache de queries frequentes
Logs estruturados
Métricas de performance
Recursos Adicionais
Documentação MCP
Turso
Contribuição
Fork o projeto
Crie uma branch:
git checkout -b feature/nomeCommit suas mudanças
Abra um Pull Request
Licença
MIT
English
About the Project
MCP Turso is the first complete solution to integrate Turso Cloud databases with Model Context Protocol (MCP) in VSCode. This project allows GitHub Copilot to interact directly with your Turso databases through MCP tools, facilitating CRUD operations and SQL queries.
Why this project exists?
First MCP solution for Turso: No implementation was available
Native VSCode integration: Works perfectly with GitHub Copilot
Easy Windows setup: Simple configuration for Windows
Complete tools: Support for all basic database operations
MCP Architecture
How MCP Works
Model Context Protocol (MCP) is an open protocol that allows Large Language Models (LLMs) to connect to external tools and data in a standardized way.
Main Components:
MCP Client: Application that uses the protocol (e.g., GitHub Copilot, Claude Desktop)
MCP Server: Program that exposes tools and resources (this project)
Communication: Via stdio (stdin/stdout) using JSON-RPC 2.0
Operation Flow:
MCP Client starts the server
Server registers its tools via
ListToolsClient can call tools via
CallToolServer executes the operation and returns result
Security:
SELECT queries are automatically validated
Write operations use prepared statements
Local communication via stdio (no network ports exposed)
Project Structure
mcp-turso/
├── src/
│ └── index.ts # Main MCP server
├── dist/ # Compiled code (generated)
├── .env # Environment variables (not versioned)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This documentationPrerequisites
Node.js 18+ (compatible with dependencies)
A Turso Cloud account with active database
VSCode with GitHub Copilot installed
Installation
Step 1: Create the project
# Create project folder
mkdir mcp-turso
cd mcp-turso
# Initialize Node.js project
npm init -yStep 2: Install dependencies
npm install @modelcontextprotocol/sdk @libsql/client dotenv
npm install -D typescript @types/node tsxStep 3: Configure TypeScript
Create tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "bundler",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"resolveJsonModule": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}Step 4: Create server code
Create src folder and src/index.ts with the code provided in the repository.
Step 5: Configure package.json
Edit package.json to include:
{
"name": "mcp-turso",
"version": "1.0.0",
"type": "module",
"bin": {
"mcp-turso": "./dist/index.js"
},
"scripts": {
"build": "tsc",
"dev": "tsx src/index.ts",
"start": "node dist/index.js"
},
"dependencies": {
"@libsql/client": "^0.14.0",
"@modelcontextprotocol/sdk": "^1.0.4",
"dotenv": "^16.4.5"
},
"devDependencies": {
"@types/node": "^22.10.2",
"tsx": "^4.19.2",
"typescript": "^5.7.2"
}
}Step 6: Build the project
npm run buildThis creates the dist/ folder with compiled JavaScript code.
Configuration
Environment Variables
Create a .env file in the project root:
TURSO_DATABASE_URL=libsql://your-database.turso.io
TURSO_AUTH_TOKEN=your-token-hereTo get the token:
turso auth tokenVSCode Configuration
Step 1: Create MCP file
In the root of your project (not mcp-turso), create .vscode/mcp.json:
{
"mcpServers": {
"turso": {
"command": "node",
"args": ["C:/full/path/mcp-turso/dist/index.js"],
"env": {
"TURSO_DATABASE_URL": "libsql://your-database.turso.io",
"TURSO_AUTH_TOKEN": "your-token-here"
}
}
}
}Important: Replace C:/full/path/ with the actual path where you created the mcp-turso project.
Step 2: Restart VSCode
Close VSCode completely and reopen to load the MCP configuration.
Usage in GitHub Copilot
Open Copilot Chat (Ctrl + Shift + I) and test commands:
List all tables in my times databaseShow the structure of the players tableCount how many players are confirmedInsert a new player: name "Carlos", whatsapp "11987654321"Add a phone column of type TEXT to the players tableCreate a unique index on user emailsAdd a foreign key between players and teamsAvailable Tools
Tool | Description | Example |
| Lists all tables |
|
| Shows table structure |
|
| Executes SELECT (read-only) |
|
| Inserts data |
|
| Updates data |
|
| Deletes data |
|
| Counts records |
|
| Adds column to table |
|
| Executes DDL commands |
|
| Creates index |
|
| Adds constraint |
|
| Begins transaction |
|
| Commits transaction |
|
| Rollbacks transaction |
|
API Reference
Detailed Tool Schemas
list_tables
Description: Lists all database tables Parameters: None Return: List of table names
describe_table
Description: Shows complete table structure Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Name of the table to describe"
}
},
"required": ["table"]
}Return: Table schema with columns, types and constraints
execute_select
Description: Executes a SELECT query (read-only) Parameters:
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Valid SQL SELECT query"
}
},
"required": ["query"]
}Validation: Query must start with "SELECT" (case insensitive) Return: Query result in JSON format
insert_data
Description: Inserts a new record into the table Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Table name"
},
"data": {
"type": "object",
"description": "Object with data to insert",
"additionalProperties": true
}
},
"required": ["table", "data"]
}Return: ID of the inserted record
update_data
Description: Updates existing records Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Table name"
},
"data": {
"type": "object",
"description": "Data to update",
"additionalProperties": true
},
"where": {
"type": "string",
"description": "WHERE condition to identify records"
}
},
"required": ["table", "data", "where"]
}Return: Number of affected records
delete_data
Description: Removes records from the table Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Table name"
},
"where": {
"type": "string",
"description": "WHERE condition to identify records"
}
},
"required": ["table", "where"]
}Return: Number of removed records
count_rows
Description: Counts records in a table Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Table name"
},
"where": {
"type": "string",
"description": "Optional WHERE condition"
}
},
"required": ["table"]
}Return: Total number of records
add_column
Description: Adds a new column to an existing table Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Table name"
},
"column": {
"type": "string",
"description": "Name of the new column"
},
"type": {
"type": "string",
"description": "Data type of the column (e.g., 'TEXT', 'INTEGER', 'REAL', 'BLOB')"
},
"nullable": {
"type": "boolean",
"description": "Whether the column can be NULL (default: true)",
"default": true
},
"default_value": {
"type": "string",
"description": "Default value for the column (optional)"
}
},
"required": ["table", "column", "type"]
}Return: Confirmation of column addition
execute_ddl
Description: Executes safe DDL (Data Definition Language) commands Parameters:
{
"type": "object",
"properties": {
"sql": {
"type": "string",
"description": "Valid DDL SQL command (ALTER TABLE, CREATE INDEX, etc.)"
}
},
"required": ["sql"]
}Validation: Blocks DROP, TRUNCATE, DELETE commands. Allows only ALTER TABLE, CREATE INDEX, ADD CONSTRAINT Return: Confirmation of command execution
create_index
Description: Creates an index on a specific column Parameters:
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Index name"
},
"table": {
"type": "string",
"description": "Table name"
},
"column": {
"type": "string",
"description": "Column name"
},
"unique": {
"type": "boolean",
"description": "Whether it should be a unique index",
"default": false
}
},
"required": ["name", "table", "column"]
}Return: Confirmation of index creation
add_constraint
Description: Adds constraints (foreign key, check, unique) to tables Parameters:
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Table name"
},
"constraint_name": {
"type": "string",
"description": "Constraint name"
},
"constraint_type": {
"type": "string",
"description": "Type: 'FOREIGN KEY', 'CHECK', 'UNIQUE'",
"enum": ["FOREIGN KEY", "CHECK", "UNIQUE"]
},
"columns": {
"type": "array",
"items": {"type": "string"},
"description": "Columns involved"
},
"referenced_table": {
"type": "string",
"description": "Referenced table (for FK)"
},
"referenced_columns": {
"type": "array",
"items": {"type": "string"},
"description": "Referenced columns (for FK)"
},
"check_expression": {
"type": "string",
"description": "CHECK expression (for CHECK)"
}
},
"required": ["table", "constraint_name", "constraint_type", "columns"]
}Return: Confirmation of constraint addition
begin_transaction
Description: Begins a new transaction Parameters: None Return: Confirmation of transaction start
commit_transaction
Description: Commits all operations in the current transaction Parameters: None Return: Confirmation of commit
rollback_transaction
Description: Cancels all operations in the current transaction Parameters: None Return: Confirmation of rollback
Development
},
"column": {
"type": "string",
"description": "Nome da coluna"
},
"unique": {
"type": "boolean",
"description": "Se deve ser índice único",
"default": false
}
}, "required": ["name", "table", "column"] }
**Return**: Confirmação da criação do índice
#### `add_constraint`
**Descrição**: Adiciona constraints (foreign key, check, unique) a tabelas
**Parâmetros**:
```json
{
"type": "object",
"properties": {
"table": {
"type": "string",
"description": "Nome da tabela"
},
"constraint_name": {
"type": "string",
"description": "Nome da constraint"
},
"constraint_type": {
"type": "string",
"description": "Tipo: 'FOREIGN KEY', 'CHECK', 'UNIQUE'",
"enum": ["FOREIGN KEY", "CHECK", "UNIQUE"]
},
"columns": {
"type": "array",
"items": {"type": "string"},
"description": "Colunas envolvidas"
},
"referenced_table": {
"type": "string",
"description": "Tabela referenciada (para FK)"
},
"referenced_columns": {
"type": "array",
"items": {"type": "string"},
"description": "Colunas referenciadas (para FK)"
},
"check_expression": {
"type": "string",
"description": "Expressão CHECK (para CHECK)"
}
},
"required": ["table", "constraint_name", "constraint_type", "columns"]
}Return: Confirmação da adição da constraint
begin_transaction
Descrição: Inicia uma nova transação Parâmetros: Nenhum Return: Confirmação do início da transação
commit_transaction
Descrição: Confirma todas as operações da transação atual Parâmetros: Nenhum Return: Confirmação do commit
rollback_transaction
Descrição: Cancela todas as operações da transação atual Parâmetros: Nenhum Return: Confirmação do rollback
Development
For local development:
npm run dev # Runs with tsx (hot reload)Troubleshooting
"command not found" error
Use absolute path in
argsin.vscode/mcp.jsonExample:
C:/Users/Lucas Silva/projects/mcp-turso/dist/index.js
Permission error
On first use, Copilot will ask for permission
Click "Allow" or "Continue"
Tools don't appear
Make sure
npm run buildwas executedRestart VSCode completely
Confirm the path in
.vscode/mcp.jsonis correctCheck logs in Output → MCP
Turso connection error
Confirm
TURSO_DATABASE_URLandTURSO_AUTH_TOKENare correctRun
turso auth tokento generate a new token if needed
Available Scripts
npm run build: Compiles TypeScriptnpm run dev: Runs in development modenpm start: Runs compiled version
Roadmap
Upcoming Features
SQL transactions support
Complex queries with JOIN
Database backup and restore
Optional web interface for administration
Support for multiple Turso databases
Integration with other MCP tools
Planned Improvements
More rigorous schema validation
Support for advanced data types
Cache for frequent queries
Structured logging
Performance metrics
Additional Resources
MCP Documentation
Turso
Contributing
Fork the project
Create a branch:
git checkout -b feature/nameCommit your changes
Open a Pull Request
License
MIT
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Lucasvicentedasilva/mcp-turso'
If you have feedback or need assistance with the MCP directory API, please join our Discord server