MotherDuck MCP Server

Servidor MCP Local DuckDB / MotherDuck

Análises SQL e engenharia de dados para Assistentes de IA e IDEs.

Conecte assistentes de IA aos seus dados usando o poderoso motor SQL analítico do DuckDB. Suporta conexão com arquivos DuckDB locais, bancos de dados em memória, bancos de dados hospedados no S3 e MotherDuck. Permite executar consultas SQL de leitura e escrita, navegar pelos catálogos de bancos de dados e alternar entre diferentes conexões de banco de dados em tempo real.

Procurando um servidor MCP remoto totalmente gerenciado para MotherDuck? → Acesse a documentação do MCP Remoto MotherDuck

MCP Remoto vs Local

📝 Migrando da v0.x?

• Somente leitura por padrão: O servidor agora executa em modo somente leitura por padrão. Adicione --read-write para habilitar acesso de escrita. Veja Protegendo para Produção.
• Banco de dados padrão alterado: O padrão de --db-path mudou de md: para :memory:. Adicione --db-path md: explicitamente para MotherDuck.
• Somente leitura no MotherDuck requer token de escalonamento de leitura: Conexões MotherDuck em modo somente leitura requerem um token de escalonamento de leitura. Tokens regulares requerem --read-write.

Início Rápido

Pré-requisitos: Instale o uv via pip install uv ou brew install uv

Conectando ao DuckDB em Memória (Modo Dev)

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

Flexibilidade total sem restrições — acesso de leitura e escrita e a capacidade de alternar para qualquer banco de dados (arquivos locais, S3 ou MotherDuck) em tempo de execução.

Conectando a um Arquivo DuckDB Local em Modo Somente Leitura

{
  "mcpServers": {
    "DuckDB (read-only)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/absolute/path/to/your.duckdb"]
    }
  }
}

Conecta a um arquivo DuckDB específico em modo somente leitura. Não manterá o bloqueio do arquivo, sendo conveniente para uso simultâneo com uma conexão de escrita para o mesmo arquivo DuckDB. Você também pode conectar a arquivos DuckDB remotos no S3 usando s3://bucket/path.duckdb — veja Variáveis de Ambiente para autenticação S3. Se estiver considerando acesso de terceiros ao MCP, veja Protegendo para Produção.

Conectando ao MotherDuck em Modo Leitura-Escrita

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Veja Parâmetros de Linha de Comando para mais opções, Protegendo para Produção para orientações de implantação e Solução de Problemas se encontrar dificuldades.

Configuração do Cliente

Cliente	Local da Configuração	Instalação com Um Clique
Claude Desktop	Configurações → Desenvolvedor → Editar Config	.mcpb (Pacote MCP)
Claude Code	Use os comandos CLI abaixo	-
Codex CLI	Use os comandos CLI abaixo ou ~/.codex/config.toml	-
Gemini CLI	Use os comandos CLI abaixo ou ~/.gemini/settings.json	-
Cursor	Configurações → MCP → Adicionar novo servidor MCP global
VS Code	Ctrl+Shift+P → "Preferências: Abrir Configurações do Usuário (JSON)"
Kiro	~/.kiro/settings/mcp.json (global) ou .kiro/settings/mcp.json (projeto)

Qualquer cliente compatível com MCP pode usar este servidor. Adicione a configuração JSON do Início Rápido ao arquivo de configuração MCP do seu cliente. Consulte a documentação do seu cliente para a localização do arquivo de configuração.

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

claude mcp add --scope user duckdb --transport stdio -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

claude mcp add --scope user motherduck --transport stdio --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

codex mcp add duckdb -- uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

codex mcp add motherduck --env motherduck_token=YOUR_TOKEN -- uvx mcp-server-motherduck --db-path md: --read-write

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path :memory: --read-write --allow-switch-databases

gemini mcp add -s user duckdb uvx mcp-server-motherduck --db-path /absolute/path/to/db.duckdb

gemini mcp add -s user -e motherduck_token=YOUR_TOKEN motherduck uvx mcp-server-motherduck --db-path md: --read-write

{
  "mcpServers": {
    "DuckDB (in-memory, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", ":memory:", "--read-write", "--allow-switch-databases"]
    }
  }
}

{
  "mcpServers": {
    "MotherDuck (local, r/w)": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "md:", "--read-write"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Ferramentas

*Requer a flag --allow-switch-databases

Todas as ferramentas retornam JSON. Os resultados são limitados a 1024 linhas / 50.000 caracteres por padrão (configurável via --max-rows, --max-chars).

Protegendo para Produção

Ao conceder acesso de terceiros a um servidor MCP auto-hospedado, o modo somente leitura por si só não é suficiente — ele ainda permite acesso ao sistema de arquivos local, alteração de configurações do DuckDB e outras operações potencialmente sensíveis.

Para implantações em produção com acesso de terceiros, recomendamos o MCP Remoto MotherDuck — configuração zero, capacidade de leitura-escrita e hospedado pela MotherDuck.

Auto-hospedando o MCP MotherDuck: Faça um fork deste repositório e personalize conforme necessário. Use uma conta de serviço com tokens de escalonamento de leitura e habilite o modo SaaS para restringir o acesso a arquivos locais.

Auto-hospedando o MCP DuckDB: Use --init-sql para aplicar configurações de segurança. Veja o guia de Proteção do DuckDB para opções disponíveis.

Parâmetros de Linha de Comando

Variáveis de Ambiente

Solução de Problemas

• spawn uvx ENOENT: Especifique o caminho completo para uvx (execute which uvx para encontrá-lo)
• Arquivo bloqueado: Certifique-se de que --ephemeral-connections está ativado (padrão: true) e que você não está conectado em modo leitura-escrita

Recursos

• Documentação do MCP MotherDuck
• Feche o Ciclo: Pipelines de Dados Mais Rápidos com MCP, DuckDB e IA (Blog)
• Pipelines de Dados Mais Rápidos com MCP e DuckDB (YouTube)

Desenvolvimento

Para executar a partir do código fonte:

{
  "mcpServers": {
    "Local DuckDB (Dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-server-motherduck", "run", "mcp-server-motherduck", "--db-path", "md:"],
      "env": {
        "motherduck_token": "<YOUR_MOTHERDUCK_TOKEN>"
      }
    }
  }
}

Processo de Lançamento

1. Execute a GitHub Action Release New Version
2. Insira a versão no formato MAJOR.MINOR.PATCH
3. O fluxo de trabalho incrementa a versão, publica no PyPI/registro MCP e cria o lançamento no GitHub com o pacote MCPB

Licença

Licença MIT - veja o arquivo LICENSE.

mcp-name: io.github.motherduckdb/mcp-server-motherduck