Python MSSQL MCP Server

Python MSSQL MCP Server

Uma implementação de servidor Model Context Protocol em Python que fornece acesso a bancos de dados Microsoft SQL Server. Este servidor permite que Modelos de Linguagem inspecionem esquemas de tabelas e executem consultas SQL por meio de uma interface padronizada.

Recursos

Funcionalidade Principal

• Operação assíncrona usando asyncio do Python
• Configuração baseada em ambiente usando python-dotenv
• Sistema abrangente de logging
• Pool de conexões e gerenciamento via pyodbc
• Tratamento de erros e recuperação
• Integração FastAPI para endpoints de API
• Modelos Pydantic para validação de dados
• Gerenciamento de conexão MSSQL com ODBC Driver

Pré-requisitos

• Python 3.x
• Pacotes Python necessários:
  • pyodbc
  • pydantic
  • python-dotenv
  • mcp-server
• ODBC Driver 17 para SQL Server

Instalação

git clone https://github.com/amornpan/py-mcp-mssql.git
cd py-mcp-mssql
pip install -r requirements.txt

Capturas de Tela

A captura de tela acima demonstra o servidor sendo usado com Claude para analisar e visualizar dados SQL.

Estrutura do Projeto

PY-MCP-MSSQL/
├── src/
│   └── mssql/
│       ├── __init__.py
│       └── server.py
├── tests/
│   ├── __init__.py
│   ├── test_mssql.py
│   └── test_packages.py
├── .env
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

Explicação da Estrutura de Diretórios

• src/mssql/ - Diretório principal do código-fonte
  • __init__.py - Inicialização do pacote
  • server.py - Implementação principal do servidor
• tests/ - Diretório de arquivos de teste
  • __init__.py - Inicialização do pacote de teste
  • test_mssql.py - Testes de funcionalidade MSSQL
  • test_packages.py - Testes de dependências do pacote
• .env - Arquivo de configuração de ambiente (não no git)
• .env.example - Exemplo de configuração de ambiente
• .gitignore - Regras de ignorar do Git
• README.md - Documentação do projeto
• requirements.txt - Dependências do projeto

Configuração

Crie um arquivo .env na raiz do projeto:

MSSQL_SERVER=your_server
MSSQL_DATABASE=your_database
MSSQL_USER=your_username
MSSQL_PASSWORD=your_password
MSSQL_DRIVER={ODBC Driver 17 for SQL Server}

Detalhes da Implementação da API

Listagem de Recursos

@app.list_resources()
async def list_resources() -> list[Resource]

• Lista todas as tabelas disponíveis no banco de dados
• Retorna nomes de tabelas com URIs no formato mssql://<table_name>/data
• Inclui descrições de tabelas e tipos MIME

Leitura de Recursos

@app.read_resource()
async def read_resource(uri: AnyUrl) -> str

• Lê dados da tabela especificada
• Aceita URIs no formato mssql://<table_name>/data
• Retorna as primeiras 100 linhas em formato CSV
• Inclui cabeçalhos de colunas

Execução de SQL

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]

• Executa consultas SQL
• Suporta consultas SELECT e de modificação
• Retorna resultados em formato CSV para consultas SELECT
• Retorna o número de linhas afetadas para consultas de modificação

Uso com Claude Desktop

Adicione à sua configuração do Claude Desktop:

No MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json No Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mssql": {
      "command": "python",
      "args": [
        "server.py"
      ],
      "env": {
        "MSSQL_SERVER": "your_server",
        "MSSQL_DATABASE": "your_database",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DRIVER": "{ODBC Driver 17 for SQL Server}"
      }
    }
  }
}

Tratamento de Erros

O servidor implementa tratamento abrangente de erros para:

• Falhas de conexão com o banco de dados
• Consultas SQL inválidas
• Erros de acesso a recursos
• Validação de URI
• Erros de execução de ferramentas

Todos os erros são registrados e retornados com mensagens de erro apropriadas.

Recursos de Segurança

• Configuração baseada em variáveis de ambiente
• Segurança da string de conexão
• Limites de tamanho do conjunto de resultados
• Validação de entrada via Pydantic
• Tratamento adequado de consultas SQL

Informações de Contato

Amornpan Phornchaicharoen

Sinta-se à vontade para entrar em contato comigo se tiver alguma dúvida sobre este projeto ou quiser colaborar!

---

Feito com ❤️ por Amornpan Phornchaicharoen

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Autor

Amornpan Phornchaicharoen

Contribuindo

1. Faça um fork do repositório
2. Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
4. Envie para a branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

Requisitos

Crie um arquivo requirements.txt com:

fastapi>=0.104.1
pydantic>=2.10.6
uvicorn>=0.34.0 
python-dotenv>=1.0.1
pyodbc>=4.0.35
anyio>=4.5.0
mcp==1.2.0

Estas versões foram testadas e verificadas para funcionar juntas. Os componentes principais são:

• fastapi e uvicorn para o servidor de API
• pydantic para validação de dados
• pyodbc para conectividade com SQL Server
• mcp para implementação do Model Context Protocol
• python-dotenv para configuração de ambiente
• anyio para suporte a I/O assíncrono

Agradecimentos

• Equipe do Microsoft SQL Server pelos drivers ODBC
• Mantenedores do pyodbc do Python
• Comunidade do Model Context Protocol
• Contribuidores do projeto python-dotenv