libSQL by xexr

Servidor MCP para bancos de dados libSQL com ferramentas abrangentes de segurança e gerenciamento. Suporta bancos de dados de arquivo, HTTP local e Turso remoto com pooling de conexões, suporte a transações e 6 ferramentas especializadas de banco de dados.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP libSQL by xexr

Um servidor Model Context Protocol (MCP) para operações de banco de dados libSQL, fornecendo acesso seguro ao banco de dados através do Claude Desktop, Claude Code, Cursor e outros clientes compatíveis com MCP.

Executa em Node, escrito em TypeScript

🔧 Início Rápido

Instale:
```
pnpm install -g @xexr/mcp-libsql
```

Teste localmente:

mcp-libsql --url file:///tmp/test.db --log-mode console

Configure o Claude Desktop com o caminho do seu Node.js e a URL do banco de dados (veja exemplos de configuração abaixo)

🚀 Status

✅ Capacidades completas de gerenciamento de banco de dados - Todas as 6 ferramentas principais implementadas e testadas
✅ Validação de segurança abrangente - 67 testes de segurança cobrindo todos os vetores de injeção
✅ Cobertura extensiva de testes - 244 testes no total (177 unitários + 67 de segurança) com 100% de taxa de aprovação
✅ Implantação de produção verificada - Funcionando com sucesso com clientes MCP
✅ Tratamento robusto de erros - Retry de conexão, degradação graciosa e registro de auditoria

🛠️ Recursos

Ferramentas Disponíveis

read-query: Executa consultas SELECT com validação de segurança abrangente
write-query: Operações INSERT/UPDATE/DELETE com suporte a transações
create-table: Operações DDL para criação de tabelas com medidas de segurança
alter-table: Modificações de estrutura de tabela (operações ADD/RENAME/DROP)
list-tables: Navegação de metadados do banco de dados com opções de filtro
describe-table: Inspeção de esquema de tabela com múltiplos formatos de saída

Segurança e Confiabilidade

Prevenção de injeção SQL em múltiplas camadas com validação de segurança abrangente
Pool de conexões com monitoramento de saúde e lógica automática de retry
Suporte a transações com rollback automático em caso de erros
Registro de auditoria abrangente para conformidade de segurança

🔐 Detalhes de segurança: Veja docs/SECURITY.md para recursos de segurança abrangentes e testes.

Experiência do Desenvolvedor

Formatação bonita de tabelas com alinhamento adequado e tratamento de NULL
Métricas de desempenho exibidas para todas as operações
Mensagens de erro claras com contexto acionável
Suporte a consultas parametrizadas para manipulação segura de dados
Modo de desenvolvimento com registro aprimorado e hot reload

📋 Pré-requisitos

Node.js 20+
pnpm (ou npm) gerenciador de pacotes
Banco de dados libSQL (baseado em arquivo ou remoto)
Claude Desktop (para integração MCP)

Requisitos de Plataforma

macOS: Instalação nativa do Node.js
Linux: Instalação nativa do Node.js
Windows: Instalação nativa do Node.js ou WSL2 com instalação do Node.js

🔧 Instalação

# Use your package manager of choice, e.g. npm, pnpm, bun etc

# Install globally
pnpm install -g @xexr/mcp-libsql
mcp-libsql -v # check version

# ...or build from the repository
git clone https://github.com/Xexr/mcp-libsql.git
cd mcp-libsql
pnpm install # Install dependencies
pnpm build # Build the project
node dist/index.js -v  # check version

🚀 Uso

Teste Local

Instalação global assumida abaixo, substitua "mcp-libsql" por "node dist/index.js" se estiver usando build local

# Test with file database (default: file-only logging)
mcp-libsql --url file:///tmp/test.db

# Test with HTTP database
mcp-libsql --url http://127.0.0.1:8080

# Test with Turso database (environment variable, alternatively export the env var)
LIBSQL_AUTH_TOKEN="your-token" mcp-libsql --url "libsql://your-db.turso.io"

# Test with Turso database (CLI parameter)
mcp-libsql --url "libsql://your-db.turso.io" --auth-token "your-token"

# Development mode with console logging
mcp-libsql --dev --log-mode console --url file:///tmp/test.db

# Test with different logging modes
mcp-libsql --url --log-mode both file:///tmp/test.db

Integração com Claude Desktop

Configure o servidor MCP no Claude Desktop com base no seu sistema operacional:

Configuração macOS

Crie o arquivo de configuração em ~/Library/Application Support/Claude/claude_desktop_config.json:

Instalação global


{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///Users/username/database.db"
      ]
    }
  }
}

Configuração alternativa para instalação com build local:

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-libsql/dist/index.js",
        "--url", 
        "file:///Users/username/database.db"
      ],
    }
  }
}

Configuração alternativa para instalação global usando nvm lts para node

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "zsh",
      "args": [
        "-c",
        "source ~/.nvm/nvm.sh && nvm use --lts > /dev/null && mcp-libsql --url file:///Users/username/database.db",
      ],
    }
  }
}

Importante: O método de instalação global é recomendado, pois lida com o PATH automaticamente.

Configuração Linux

Crie o arquivo de configuração em ~/.config/Claude/claude_desktop_config.json:

Instalação global

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "file:///home/username/database.db"
      ]
    }
  }
}

Configuração alternativa para instalação com build local:

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "node",
      "args": [
        "/home/username/projects/mcp-libsql/dist/index.js",
        "--url",
        "file:///home/username/database.db"
      ],
    }
  }
}

Configuração Windows (WSL2)

Crie o arquivo de configuração em %APPDATA%\Claude\claude_desktop_config.json:

Instalação global

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

Configuração alternativa para instalação com build local:

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "/home/username/projects/mcp-libsql/dist/index.js --url file:///home/username/database.db",
      ]
    }
  }
}

Configuração alternativa para instalação global usando nvm para node

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "wsl.exe",
      "args": [
        "-e",
        "bash",
        "-c",
        "source ~/.nvm/nvm.sh && mcp-libsql --url file:///home/username/database.db",
      ]
    }
  }
}

Importante: Use wsl.exe -e (não apenas wsl.exe) para garantir o manuseio adequado de comandos e evitar problemas com o recebimento de comandos do servidor no Windows.

Autenticação do Banco de Dados

Para bancos de dados Turso (e outros com credenciais), você precisará de um token de autenticação. Existem duas maneiras seguras de fornecê-lo:

Instalação global mostrada abaixo, ajuste conforme sua configuração

Método 1: Variável de Ambiente (Recomendado)

Configure o Claude Desktop com variável de ambiente (exemplo macOS/Linux):

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io"
      ]
    }
  }
}

Método 2: Parâmetro CLI

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://your-database.turso.io",
        "--auth-token",
        "your-turso-auth-token-here"
      ]
    }
  }
}

Obtendo Seu Token de Autenticação Turso

Instale o CLI do Turso:

curl -sSfL https://get.tur.so/install.sh | bash

Faça login no Turso:
```
turso auth login
```

Crie um token de autenticação:

turso auth token create --name "mcp-libsql"

Obtenha a URL do seu banco de dados:
```
turso db show your-database-name --url
```

Boas Práticas de Segurança

Variáveis de ambiente são mais seguras do que parâmetros CLI (tokens não aparecem em listas de processos)
Arquivos de configuração MCP podem conter tokens - certifique-se de que não sejam commitados no controle de versão
Considere usar gerenciamento externo de segredos para ambientes de produção
Use tokens com escopo com as permissões mínimas necessárias
Rotacione tokens regularmente para maior segurança
Monitore o uso de tokens através do painel do Turso

Exemplo: Configuração Completa do Turso

Crie e configure o banco de dados:

# Create database
turso db create my-app-db

# Get database URL
turso db show my-app-db --url
# Output: libsql://my-app-db-username.turso.io

# Create auth token
turso auth token create --name "mcp-libsql-token"
# Output: your-long-auth-token-string

Configure o Claude Desktop:

export LIBSQL_AUTH_TOKEN="your-turso-auth-token-here"

{
  "mcpServers": {
    "mcp-libsql": {
      "command": "mcp-libsql",
      "args": [
        "--url",
        "libsql://my-app-db-username.turso.io"
      ]
    }
  }
}

Teste a conexão:

# Test locally first
mcp-libsql --url "libsql://my-app-db-username.turso.io" --log-mode console

Notas de Configuração

Caminhos de arquivo: Use caminhos absolutos para evitar problemas de resolução de caminho
URLs de banco de dados:
- Bancos de dados de arquivo: file:///absolute/path/to/database.db
- Bancos de dados HTTP: http://hostname:port
- libSQL/Turso: libsql://your-database.turso.io
Caminho do Node.js: Use which node para encontrar o caminho de instalação do seu Node.js
Diretório de trabalho: Defina cwd para garantir que caminhos relativos funcionem corretamente
Autenticação: Para bancos de dados Turso, use variáveis de ambiente para manuseio seguro de tokens
Modos de registro:
- O modo padrão file evita erros de parsing JSON no protocolo MCP
- Use --log-mode console para depuração de desenvolvimento
- Use --log-mode both para registro abrangente
- Use --log-mode none para desabilitar todo o registro

Reinicie o Claude Desktop completamente após atualizar a configuração
Teste a integração pedindo ao Claude para executar consultas SQL:
```
Can you run this SQL query: SELECT 1 as test
```

📋 Ferramentas Disponíveis

read-query - Executa consultas SELECT com validação de segurança
write-query - INSERT/UPDATE/DELETE com suporte a transações
create-table - CREATE TABLE com segurança DDL
alter-table - Modifica a estrutura da tabela (ADD/RENAME/DROP)
list-tables - Navega metadados e objetos do banco de dados
describe-table - Inspeciona o esquema e a estrutura da tabela

📖 Documentação detalhada da API: Veja docs/API.md para exemplos completos de entrada/saída e parâmetros.

🧪 Testes

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test security-verification

# Lint code
pnpm lint

# Fix linting issues
pnpm lint:fix

# Type check
pnpm typecheck

Cobertura de Testes: 403 testes cobrindo toda a funcionalidade, incluindo casos extremos, cenários de erro, argumentos CLI, autenticação e validação de segurança abrangente.

⚠️ Problemas Comuns

1. Falhas de Build

# Clean and rebuild
rm -rf dist node_modules
pnpm install && pnpm build

2. Problemas de Versão do Node.js (macOS)

SyntaxError: Unexpected token '??='

Problema: O Claude Desktop pode usar por padrão uma versão mais antiga do Node.js no seu sistema que não suporta o conjunto de recursos necessário.

Solução: Use a instalação global e o método de seleção de nvm node mostrado acima.

3. Servidor Não Inicia

Para instalação global: pnpm install -g @xexr/mcp-libsql
Para instalação local: Certifique-se de que pnpm build foi executado e dist/index.js existe
Teste localmente: mcp-libsql --url file:///tmp/test.db
Reinicie o Claude Desktop após alterações de configuração

4. Ferramentas Indisponíveis

Verifique se a URL do banco de dados está acessível
Verifique os logs do Claude Desktop para erros de conexão
Teste com um banco de dados de arquivo simples: file:///tmp/test.db

5. Erros de Parsing JSON (Resolvido)

Expected ',' or ']' after array element in JSON

Resolvido: Este problema é causado pelo registro no console stdout. A opção --log-mode agora tem como padrão o modo file, o que evita este problema. Se você vir esses erros, certifique-se de estar usando o padrão --log-mode file ou não especifique --log-mode de forma alguma. Observe que o erro é inofensivo, e a ferramenta ainda funcionará com ele se você desejar ter registro no console.

6. Problemas de Conexão com o Banco de Dados

# Test database connectivity
sqlite3 /tmp/test.db "SELECT 1"

# Fix permissions
chmod 644 /path/to/database.db

🔧 Guia completo de solução de problemas: Veja docs/TROUBLESHOOTING.md para soluções detalhadas para todos os problemas.

🏗️ Arquitetura

Construído com TypeScript e padrões modernos de Node.js:

Pool de conexões com monitoramento de saúde e lógica de retry
Arquitetura baseada em ferramentas com validação e tratamento de erros consistentes
Design com foco em segurança com validação de entrada em múltiplas camadas
Testes abrangentes com 244 testes cobrindo todos os cenários

🤝 Contribuindo

Siga o modo estrito do TypeScript e os padrões de código existentes
Escreva testes para novos recursos
Mantenha as medidas de segurança
Atualize a documentação

Desenvolvimento: pnpm dev • Build: pnpm build • Teste: pnpm test

📄 Licença

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

libSQL by xexr

Documentação

MCP libSQL by xexr

🔧 Início Rápido

🚀 Status

🛠️ Recursos

Ferramentas Disponíveis

Segurança e Confiabilidade

Experiência do Desenvolvedor

📋 Pré-requisitos

Requisitos de Plataforma

🔧 Instalação

🚀 Uso

Teste Local

Integração com Claude Desktop

Configuração macOS

Configuração Linux

Configuração Windows (WSL2)

Autenticação do Banco de Dados

Método 1: Variável de Ambiente (Recomendado)

Método 2: Parâmetro CLI

Obtendo Seu Token de Autenticação Turso

Boas Práticas de Segurança

Exemplo: Configuração Completa do Turso

Notas de Configuração

📋 Ferramentas Disponíveis

🧪 Testes

⚠️ Problemas Comuns

1. Falhas de Build

2. Problemas de Versão do Node.js (macOS)

3. Servidor Não Inicia

4. Ferramentas Indisponíveis

5. Erros de Parsing JSON (Resolvido)

6. Problemas de Conexão com o Banco de Dados

🏗️ Arquitetura

🤝 Contribuindo

📄 Licença

🔗 Links