SQLite

mcp-sqlite

Forneça dados úteis a agentes de IA sem dar a eles acesso a sistemas externos. Compatível com Datasette para usuários humanos!

Recursos

• Agentes de IA podem obter a estrutura de todas as tabelas e colunas no banco de dados SQLite em um único comando - sqlite_get_catalog.
  • O catálogo pode ser enriquecido com descrições para as tabelas e colunas usando um simples arquivo de metadados YAML ou JSON.
• O mesmo arquivo de metadados pode conter consultas pré-definidas para o agente de IA usar. Cada consulta pré-definida será transformada em uma ferramenta MCP separada sqlite_execute_main_{tool name}.
• Agentes de IA podem executar consultas SQL arbitrárias com sqlite_execute.

Início rápido usando o Visual Studio Code

1. Instale o uv.

2. Instale o Visual Studio Code se você ainda não o tiver. Ative o GitHub Copilot.

3. Abra este repositório no VS Code. Abra um chat em modo agente do GitHub Copilot. Verifique as ferramentas disponíveis - você deve ver o MCP Server: sqlite_sample com três ferramentas disponíveis.

   

4. Você deve conseguir perguntar ao Copilot em modo agente algo como "Obter sobreviventes do Titanic com 28 anos" e obter uma resposta.

   

5. Use o arquivo de configuração MCP de exemplo mcp.json e o arquivo de metadados de exemplo titanic.yml como ponto de partida para sua própria configuração.

Exploração interativa com MCP Inspector e Datasette

Os mesmos arquivos de banco de dados e metadados podem ser usados para explorar os dados interativamente com o MCP Inspector e o Datasette.

MCP Inspector	Datasette

MCP Inspector

Use o painel do MCP Inspector para interagir com o banco de dados SQLite da mesma forma que um agente de IA faria:

1. Instale o npm.
2. Execute:

   npx @modelcontextprotocol/inspector uvx mcp-sqlite sample/titanic.db --metadata sample/titanic.yml
   

Datasette

Como os metadados mcp-sqlite são compatíveis com o arquivo de metadados do Datasette, você também pode explorar seus dados com o Datasette:

uvx datasette serve sample/titanic.db --metadata sample/titanic.yml

A compatibilidade com o Datasette permite que tanto agentes de IA quanto humanos explorem facilmente os mesmos dados locais!

Ferramentas MCP fornecidas pelo mcp-sqlite

• sqlite_get_catalog(): Ferramenta que o agente pode chamar para obter o catálogo completo dos bancos de dados, tabelas e colunas nos dados, combinado com metadados do arquivo de metadados. Em uma iteração anterior do mcp-sqlite, isso era um recurso em vez de uma ferramenta, mas os recursos não são tão amplamente suportados, então foi transformado em uma ferramenta. Se você tiver um caso de uso para o catálogo como recurso, abra uma issue e nós o traremos de volta!
• sqlite_execute(sql): Ferramenta que o agente pode chamar para executar SQL arbitrário. Os resultados da tabela são retornados como HTML. Para mais informações sobre por que o HTML é o melhor formato para LLMs processarem, veja Siu et al.
• {canned query name}({canned query args}): Uma ferramenta é criada para cada consulta pré-definida nos metadados, permitindo que o agente execute consultas predefinidas sem escrever SQL.

Uso

Opções de linha de comando

usage: mcp-sqlite [-h] [-m METADATA] [-p PREFIX] [-v] sqlite_file

CLI command to start an MCP server for interacting with SQLite data.

positional arguments:
  sqlite_file           Path to SQLite file to serve the MCP server for.

options:
  -h, --help            show this help message and exit
  -m, --metadata METADATA
                        Path to Datasette-compatible metadata YAML or JSON file.
  -p, --prefix PREFIX   Prefix for MCP tools. Defaults to no prefix.
  -v, --verbose         Be verbose. Include once for INFO output, twice for DEBUG output.

Metadados

Tabelas ocultas

Ocultar uma tabela com hidden: true a ocultará do catálogo retornado pela ferramenta MCP sqlite_get_catalog(). No entanto, observe que a tabela ainda estará acessível ao agente de IA! Nunca confie em ocultar uma tabela do catálogo como um recurso de segurança.

Consultas pré-definidas

Consultas pré-definidas são cada uma transformadas em uma ferramenta MCP separada e chamável pelo mcp-sqlite.

Por exemplo, uma consulta chamada my_canned_query se tornará uma ferramenta my_canned_query.

A funcionalidade de consultas pré-definidas ainda está em desenvolvimento ativo, com mais recursos planejados para breve:

Roteiro

Recurso de consulta do Datasette	Suportado no mcp-sqlite?
Exibido no catálogo	✅
Executável	✅
Títulos	✅
Descrições	✅
Parâmetros	✅
Parâmetros explícitos	❌ (planejado)
Ocultar SQL	✅
Restrições de escrita em consultas pré-definidas	✅
Paginação	❌ (planejado)
Consultas entre bancos de dados	❌ (planejado)
Fragmentos	❌ (não planejado)
Parâmetros mágicos	❌ (não planejado)