Servidor MCP SQLFluff | Awesome MCP Servers

sqlfluff-mcp-server

Um servidor MCP que expõe as funcionalidades de linting, correção e parsing do SQLFluff através do Model Context Protocol, permitindo que qualquer cliente compatível com MCP (Claude, outros agentes, integrações de IDE) faça lint e correção de SQL diretamente.

Este projeto é independente dos mantenedores do SQLFluff — é um wrapper leve em torno do pacote Python público sqlfluff.

Ferramentas

Ferramenta	Entrada	Resolução de configuração
`lint_file`	caminho no disco	sobe a partir do arquivo procurando por `.sqlfluff` / `pyproject.toml` / etc.
`fix_file`	caminho no disco (+ flag `write`)	mesma busca no diretório
`parse_file`	caminho no disco	mesma busca no diretório
`lint_sql`	texto SQL bruto + `dialect`	nenhuma — dialeto fornecido explicitamente
`fix_sql`	texto SQL bruto + `dialect`	nenhuma — dialeto fornecido explicitamente
`parse_sql`	texto SQL bruto + `dialect`	nenhuma — dialeto fornecido explicitamente
`list_dialects`	—	lista os nomes de dialetos suportados
`clear_config_cache`	—	limpa o cache de conteúdo dos arquivos de configuração do SQLFluff

As ferramentas *_file respeitam a configuração do projeto da mesma forma que a CLI sqlfluff faz (via FluffConfig.from_path, que percorre a árvore de diretórios procurando por .sqlfluff, pyproject.toml, setup.cfg ou tox.ini). As ferramentas *_sql são para conteúdo que ainda não foi gravado em disco (por exemplo, transmitido de um buffer do editor) e exigem que você passe dialect explicitamente, já que não há localização de arquivo para resolver a configuração.

Cache de configuração

O SQLFluff armazena em cache o conteúdo dos arquivos de configuração que lê ao percorrer uma árvore de diretórios, durante toda a vida do processo. Como este servidor é de longa duração (diferente da CLI sqlfluff, que é um processo novo a cada invocação), editar um arquivo .sqlfluff após o servidor ter iniciado não será detectado por lint_file / fix_file / parse_file até que você chame clear_config_cache. Chame-o sempre que a configuração em disco mudar, ou apenas proativamente antes de uma chamada de lint/fix/parse se não tiver certeza.

Requisitos

Python 3.10+
uv (recomendado) ou pipx/pip
mcp >=2.0.0,<3.0.0 and sqlfluff >=3.0.0 (instalados automaticamente como dependências — veja Notas sobre dependências)

Registro em um cliente MCP

Este pacote está publicado no PyPI, então não há nada para clonar ou instalar antecipadamente. Aponte a configuração do seu cliente MCP (por exemplo, .claude.json / .mcp.json para Claude Code, ou o arquivo de configuração do Claude Desktop) para ele via uvx, e ele será buscado em um cache isolado e iniciado sob demanda:

{
  "mcpServers": {
    "sqlfluff": {
      "command": "uvx",
      "args": ["sqlfluff-mcp-server"]
    }
  }
}

Sem uv? pipx run sqlfluff-mcp-server como command/args funciona da mesma forma.

Para servidores baseados em stdio como este, o próprio cliente inicia o processo — automaticamente, quando a sessão do cliente começa, não quando um prompt precisa dele pela primeira vez. Uma vez registrado, basta pedir ao cliente para fazer lint ou corrigir um arquivo SQL; o servidor já está rodando em segundo plano e as ferramentas já estão disponíveis. Se o processo do servidor falhar, o cliente o reinicia para você.

Executando manualmente (para testes/depuração local)

uvx sqlfluff-mcp-server

Isso inicia o servidor via stdio e bloqueia, aguardando um cliente MCP falar o protocolo com ele via stdin/stdout — não é algo que você executaria interativamente no dia a dia, apenas útil para verificar a instalação ou canalizar através do MCP Inspector.

Desenvolvimento

Clone o repositório para trabalhar no próprio servidor (em vez de apenas consumi-lo via uvx):

git clone <this-repo-url>
cd sqlfluff-mcp-server
uv sync --extra dev
uv run pytest
uv run ruff check .

Para apontar um cliente MCP para seu checkout local em vez da versão do PyPI (por exemplo, para testar mudanças não publicadas):

{
  "mcpServers": {
    "sqlfluff": {
      "command": "uv",
      "args": ["--directory", "/path/to/sqlfluff-mcp-server", "run", "sqlfluff-mcp-server"]
    }
  }
}

Notas sobre dependências

mcp está fixado em >=2.0.0,<3.0.0. A linha 2.0 do SDK renomeou mcp.server.fastmcp.FastMCP para mcp.server.mcpserver.MCPServer e moveu a seleção de transporte para run(transport=...); a API do decorador @mcp.tool() não mudou.
sqlfluff fica sem fixação acima de 3.0.0 — o SQLFluff lança versões com frequência razoável e este servidor depende apenas de sua API estável Linter / FluffConfig.

Licença

MIT — veja LICENSE.

SQLFluff MCP Server

Documentação