Thoth

Um servidor MCP seguro e somente leitura para consultar fontes de dados MySQL, PostgreSQL e Redis.

Documentação

Thoth MCP

Um servidor MCP somente leitura e com foco em segurança para assistentes de IA consultarem MySQL, PostgreSQL e Redis com segurança.

English · 简体中文

Cada consulta passa por um pipeline de segurança em camadas antes de chegar ao seu banco de dados — para que você possa dar a um assistente de IA acesso a dados sem entregar uma arma carregada.

Por que usar?

Somente leitura por design. Escritas são estruturalmente impossíveis — não existe caminho execute que jamais altere dados.
Defesa em profundidade. O SQL é validado de três formas (aplicação de SELECT → detecção de injeção → LIMIT automático). Os comandos Redis são restritos a uma lista de permissões explícita.
Segredos nunca saem da sua configuração. As senhas são carregadas de variáveis de ambiente e removidas de logs e mensagens de erro.
Um servidor, várias fontes de dados. Conecte-se a todos os seus bancos de dados por meio de um único endpoint MCP.
Funciona com qualquer cliente MCP — Claude Code, Cursor, Windsurf e qualquer outra coisa que fale MCP.

Recursos

Consulte várias instâncias MySQL, PostgreSQL e Redis por meio de um único servidor
Segurança SQL em três camadas (aplicação de SELECT + detecção de injeção + LIMIT automático)
Lista de permissões de comandos Redis (apenas comandos somente leitura explicitamente seguros)
Saída em Markdown para uso eficiente do contexto de IA
Transportes stdio, SSE e streamable-http
Pilha Docker Compose com dados de exemplo para desenvolvimento local

Início Rápido

Requisitos

Python 3.10+
Docker e Docker Compose (opcional, para implantação em contêineres)

Instalar e executar localmente

# Clone
git clone https://github.com/pennxiv/thoth-mcp.git
cd thoth-mcp

# Set up a virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install
pip install -e ".[dev]"

# Point at your datasources and run
export THOTH_DATASOURCES_FILE=config/datasources.yaml
python -m thoth_mcp

Executar com Docker

# Starts the server in streamable-http mode on port 8080
docker compose up -d --build

# Connect from any machine on your network:
# http://<server-ip>:8080/mcp

Conectar seu cliente MCP

Claude Code (~/.claude.json ou .mcp.json do projeto):

{
  "mcpServers": {
    "thoth": {
      "url": "http://<server-ip>:8080/mcp",
      "transport": "streamable-http"
    }
  }
}

Cursor / Windsurf (.cursor/mcp.json):

{
  "mcpServers": {
    "thoth": {
      "url": "http://<server-ip>:8080/mcp",
      "transport": "streamable-http"
    }
  }
}

Para uso apenas local, configure o cliente para iniciar o servidor via stdio — sem necessidade de exposição HTTP.

Configuração

Crie um arquivo datasources.yaml (ou defina THOTH_DATASOURCES_FILE para apontar para um):

mysql:
  prod_db:
    host: mysql.example.com
    port: 3306
    user: readonly_user
    password: ${MYSQL_PROD_PASSWORD}  # overridden via environment variable
    database: production
    min_pool_size: 1
    max_pool_size: 10

redis:
  cache:
    host: redis.example.com
    port: 6379
    db: 0
    min_pool_size: 1
    max_pool_size: 10

Fornecendo segredos

As senhas nunca devem ficar em arquivos de configuração. Substitua-as por variáveis de ambiente usando o padrão THOTH_<TYPE>__<NAME>__PASSWORD:

export THOTH_MYSQL__PROD_DB__PASSWORD=secret123
export THOTH_POSTGRES__WAREHOUSE__PASSWORD=another_secret
export THOTH_REDIS__CACHE__PASSWORD=redis_secret

Consulte config/datasources.yaml para um exemplo completo com os três tipos de fonte de dados.

Ferramentas MCP

Ferramenta	Descrição
`query_mysql(datasource, sql)`	Executa uma consulta SELECT em uma fonte de dados MySQL
`list_tables(datasource)`	Lista todas as tabelas em uma fonte de dados MySQL
`describe_table(datasource, table)`	Mostra detalhes das colunas de uma tabela MySQL
`query_postgres(datasource, sql)`	Executa uma consulta SELECT em uma fonte de dados PostgreSQL
`list_tables_postgres(datasource)`	Lista todas as tabelas em uma fonte de dados PostgreSQL (schema public)
`describe_table_postgres(datasource, table)`	Mostra detalhes das colunas de uma tabela PostgreSQL
`query_redis(datasource, command, args?)`	Executa um comando Redis seguro e somente leitura
`list_datasources()`	Lista todas as fontes de dados MySQL, PostgreSQL e Redis configuradas

Segurança

Este servidor é construído em torno da premissa de que tudo o que chega ao banco de dados deve ser somente leitura e livre de injeção.

Segurança SQL (defesa em três camadas)

Aplicação somente SELECT — apenas instruções SELECT são permitidas.
Detecção de padrões de injeção — bloqueia injeção UNION, ofuscação por comentários e ataques de múltiplas instruções.
Injeção automática de LIMIT — consultas sem cláusula LIMIT recebem um limite padrão (100 linhas) para evitar varreduras ilimitadas.

Segurança Redis

Apenas estes comandos somente leitura são permitidos: GET, HGET, HGETALL, LRANGE, SMEMBERS, TTL, TYPE, LLEN, SCARD, EXISTS, HEXISTS, SRANDMEMBER, ZCARD, ZSCORE, ZRANGE.

Comandos como SET, DEL, KEYS e FLUSHALL são explicitamente bloqueados.

Sanitização de erros

As mensagens de erro nunca expõem nomes de host, IPs, strings de conexão ou credenciais. Isso vale mesmo quando a configuração da conexão ou a execução da consulta falha.

Exposição de rede

Ao executar no modo streamable-http ou sse, o servidor escuta em 0.0.0.0:8080 por padrão. Coloque-o atrás de limites de rede autenticados — não o exponha diretamente à internet pública sem autenticação adicional. Consulte SECURITY.md.

Transportes

Modo	Caso de uso	Env
`stdio` (padrão)	Cliente e servidor na mesma máquina	`MCP_TRANSPORT=stdio`
`streamable-http`	Clientes remotos via HTTP	`MCP_TRANSPORT=streamable-http`
`sse`	Baseado em navegador / streaming unidirecional	`MCP_TRANSPORT=sse`

Variável	Padrão	Descrição
`MCP_TRANSPORT`	`stdio`	Modo de transporte
`MCP_HOST`	`0.0.0.0`	Host de escuta (apenas http/sse)
`MCP_PORT`	`8080`	Porta de escuta (apenas http/sse)
`THOTH_API_TOKEN`	(não definido)	Token Bearer obrigatório para clientes HTTP (apenas http/sse)

O modo SSE expõe /sse (conexões de clientes) e /messages/ (endpoint POST).

Autenticação por Token de API

Ao servir por transportes HTTP (streamable-http ou sse), você deve definir THOTH_API_TOKEN para proteger o servidor. Com um token definido, toda solicitação MCP deve conter um cabeçalho Authorization: Bearer <token>; solicitações sem um token válido são rejeitadas com 401 Unauthorized. O endpoint /health está sempre aberto para sondagens de monitoramento.

# On the server
export THOTH_API_TOKEN=$(openssl rand -hex 32)   # generate a strong token
export MCP_TRANSPORT=streamable-http
export MCP_PORT=8080
python -m thoth_mcp

# On the client (curl)
curl -H "Authorization: Bearer <token>" http://server:8080/mcp

Quando THOTH_API_TOKEN não está definido, a autenticação é desativada — adequado para uso local stdio, mas nunca exponha uma instância HTTP sem autenticação à internet pública.

Arquitetura

┌──────────────────────────────────────────────────────────────┐
│                      FastMCP Server                          │
│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐          │
│  │ MySQL Tools │ │PostgreSQL    │ │ Redis Tools │          │
│  │             │ │Tools         │ │             │          │
│  └──────┬──────┘ └──────┬───────┘ └──────┬──────┘          │
│         │               │                │                  │
│  ┌──────▼──────┐ ┌──────▼───────┐ ┌──────▼──────┐          │
│  │ MySQL Pool  │ │PostgreSQL    │ │ Redis Pool  │          │
│  │   Manager   │ │Pool Manager  │ │   Manager   │          │
│  └──────┬──────┘ └──────┬───────┘ └──────┬──────┘          │
│         │               │                │   ┌──────────┐  │
│  ┌──────▼──────┐ ┌──────▼───────┐ ┌──────▼──────┐          │
│  │  SQL Safety │ │  SQL Safety  │ │Redis Safety │          │
│  └──────┬──────┘ └──────┬───────┘ └──────┬──────┘          │
│         └───────────────┴────────────────┴───│  Config  │  │
│                                              └──────────┘  │
└──────────────────────────────────────────────────────────────┘
          │               │                │
     ┌────▼────┐    ┌────▼─────┐     ┌────▼────┐
     │  MySQL  │    │PostgreSQL│     │  Redis  │
     │   DB    │    │    DB    │     │Instance │
     └─────────┘    └──────────┘     └─────────┘

Desenvolvimento

# Run the test suite
pytest tests/ -v

# Run a single test file
pytest tests/test_mysql_tools.py -v

# Run with coverage
pytest tests/ --cov=src/thoth_mcp --cov-report=html

# Lint
ruff check src/ tests/

Consulte CONTRIBUTING.md para diretrizes de contribuição e CHANGELOG.md para o histórico de versões.

Estrutura do projeto

thoth-mcp/
├── src/thoth_mcp/
│   ├── config.py          # Configuration loading
│   ├── server.py          # FastMCP server assembly
│   ├── __main__.py        # Entry point
│   ├── db/                # Connection pool managers (mysql, postgresql, redis)
│   ├── tools/             # MCP tools (mysql, postgresql, redis, discovery)
│   └── utils/             # Safety layers, formatters, logging
├── tests/                 # Test suite
├── docker/                # Docker seed data
├── config/                # Example configurations
└── pyproject.toml

Licença

Licença MIT — consulte LICENSE.