MotherDuck

DuckDB / MotherDuck Local MCP Server

Análise 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 a arquivos DuckDB locais, bancos de dados em memória, bancos de dados hospedados em S3 e MotherDuck. Permite executar consultas SQL de leitura e escrita, navegar pelos catálogos de banco 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 MotherDuck Remote MCP

MCP Remoto vs Local

Início Rápido

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

Conectando ao DuckDB em Memória (Modo de Desenvolvimento)

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

Flexibilidade total sem proteções — acesso de leitura-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-se a um arquivo DuckDB específico em modo somente leitura. Não mantém o bloqueio do arquivo, sendo conveniente para uso junto a uma conexão de escrita no mesmo arquivo DuckDB. Você também pode conectar-se a arquivos DuckDB remotos em S3 usando s3://bucket/path.duckdb — consulte Variáveis de Ambiente para autenticação S3. Se você está considerando acesso de terceiros ao MCP, consulte 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>"
      }
    }
  }
}

Consulte 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 problemas.

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 o sinalizador --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 dar acesso a 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 de produção com acesso de terceiros, recomendamos o MotherDuck Remote MCP — zero configuração, com capacidade de leitura-escrita e hospedado pela MotherDuck.

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

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

Docker

Construa e execute o servidor com HTTP Streamable na porta 8000 (padrão para um DuckDB em memória):

docker build -t mcp-server-motherduck .
docker run --rm -p 8000:8000 mcp-server-motherduck

Conecte-se ao MotherDuck passando um token e substituindo o comando:

docker run --rm -p 8000:8000 \
  -e motherduck_token="$MOTHERDUCK_TOKEN" \
  mcp-server-motherduck --transport http --db-path md:

O endpoint MCP está disponível em http://localhost:8000/mcp. Os sinalizadores de CLI e variáveis de ambiente abaixo ainda se aplicam.

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 esteja ativado (padrão: true) e que você não esteja conectado em modo leitura-escrita

Recursos

• Documentação MCP do MotherDuck
• Feche o Ciclo: Pipelines de Dados Mais Rápidos com MCP, DuckDB & 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 ação do GitHub 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 do GitHub com o pacote MCPB

Licença

Licença MIT - consulte o arquivo LICENSE.

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