Servidor MCP Isthmus | Awesome MCP Servers

Isthmus

O servidor MCP para o seu banco de dados

Documentação · Início rápido · Instalação · Problemas

Isthmus é um servidor MCP local que dá aos modelos de IA acesso seguro e somente leitura ao seu banco de dados PostgreSQL. Um único binário, roda na sua máquina, e as credenciais nunca saem dela.

Isthmus demo

Início rápido

# 1. Install (pick one)
curl -fsSL https://isthmus.dev/install.sh | sh   # install script
docker pull guillermosasso/isthmus                # or Docker Hub

# 2. Add to your MCP client config (Claude Desktop example)

{
  "mcpServers": {
    "isthmus": {
      "command": "isthmus",
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

# 3. Ask your AI: "What tables are in my database?"

Consulte o guia de início rápido para configuração passo a passo com Claude Desktop, Cursor, Windsurf e outros.

Docker

Imagens são publicadas no Docker Hub a cada lançamento (linux/amd64 e linux/arm64).

docker run --rm \
  -e DATABASE_URL="postgres://user:pass@host.docker.internal:5432/mydb" \
  guillermosasso/isthmus

Ou fixe uma versão específica:

docker pull guillermosasso/isthmus:0.1.1

Para usar com Claude Desktop, aponte a configuração do MCP para o contêiner:

{
  "mcpServers": {
    "isthmus": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "DATABASE_URL=postgres://user:pass@host.docker.internal:5432/mydb",
        "guillermosasso/isthmus"
      ]
    }
  }
}

Recursos

Descoberta de esquema — explore esquemas, tabelas, colunas, chaves estrangeiras e índices (documentação)
Consultas somente leitura — execute SQL com limites de linhas e tempos limite no servidor (documentação)
Mascaramento de colunas — proteja PII com máscaras de redação, hash, parcial ou nula por coluna — aplicadas no servidor (documentação)
Mecanismo de políticas — enriqueça seu esquema com contexto de negócios para que a IA escreva melhor SQL (documentação)
Validação de SQL — lista de permissões no nível de AST via parser pg_query — apenas SELECT e EXPLAIN permitidos (documentação)
Transporte HTTP — sirva MCP via HTTP para clientes baseados na web, ChatGPT Desktop e acesso remoto (documentação)
OpenTelemetry — rastreamento distribuído e métricas para desempenho de consultas e monitoramento de erros (documentação)
Funciona com qualquer cliente MCP — Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code, ChatGPT Desktop (configuração de cliente)

Como funciona

flowchart TB
    Claude["Claude Desktop"] & Cursor["Cursor / VS Code"] -->|stdio| STDIO
    ChatGPT["ChatGPT / Web"] -->|HTTP| HTTP

    subgraph Transport["Transport"]
        STDIO["stdio"]
        HTTP["HTTP + Auth"]
    end

    STDIO & HTTP --> Router

    subgraph Tools["MCP Tools"]
        Router{{"router"}}
        Router --> Discover["discover"]
        Router --> Describe["describe_table"]
        Router --> Query["query"]
    end

    Discover & Describe --> Explorer

    subgraph Schema["Schema Explorer"]
        Explorer["Catalog Introspection"]
        Explorer --> Policy["Policy Engine"]
    end

    Query --> Validate

    subgraph Security["Security Pipeline"]
        direction TB
        Validate["AST Validation"] --> ReadOnly["Read-Only Tx"]
        ReadOnly --> RowLimit["Row Limit"]
        RowLimit --> Timeout["Timeout"]
    end

    Security --> PG[("PostgreSQL")]
    Schema --> PG

    PG --> Mask

    subgraph Post["Post-Processing"]
        direction TB
        Mask["PII Masking"] --> Sanitize["Error Sanitization"]
    end

    Post -.-> Audit["Audit Log"]
    Post -.-> OTel["OpenTelemetry"]
    Post --> Response["Safe Response"]
    Response --> Claude & Cursor & ChatGPT

    classDef client fill:#e8f4f8,stroke:#2196F3,color:#1565C0
    classDef transport fill:#fff3e0,stroke:#FF9800,color:#E65100
    classDef tools fill:#e8eaf6,stroke:#3F51B5,color:#283593
    classDef security fill:#fce4ec,stroke:#E53935,color:#b71c1c
    classDef explorer fill:#e8f5e9,stroke:#4CAF50,color:#1B5E20
    classDef postproc fill:#f3e5f5,stroke:#9C27B0,color:#4A148C
    classDef db fill:#fff8e1,stroke:#FFC107,color:#F57F17
    classDef obs fill:#eceff1,stroke:#607D8B,color:#37474F
    classDef response fill:#e0f2f1,stroke:#009688,color:#004D40

    class Claude,Cursor,ChatGPT client
    class STDIO,HTTP transport
    class Router,Discover,Describe,Query tools
    class Validate,ReadOnly,RowLimit,Timeout security
    class Explorer,Policy explorer
    class Mask,Sanitize postproc
    class PG db
    class Audit,OTel obs
    class Response response

Isthmus fica entre seu cliente de IA e seu banco de dados. Cada solicitação passa por um pipeline de segurança — o SQL é validado no nível de AST usando o próprio parser do PostgreSQL, as consultas são executadas em transações somente leitura com limites de linhas e tempos limite no servidor, e colunas de PII são mascaradas antes que os resultados cheguem à IA. O mecanismo de políticas enriquece os metadados do esquema com contexto de negócios para que a IA escreva melhor SQL. Toda atividade é registrada em um log de auditoria somente anexação, com rastreamento opcional via OpenTelemetry.

Ferramentas MCP

Ferramenta	O que faz
`list_schemas`	Descubra esquemas de banco de dados disponíveis
`list_tables`	Tabelas com contagens de linhas, tamanhos e descrições
`describe_table`	Colunas, tipos, chaves, índices e estatísticas
`profile_table`	Análise aprofundada: linhas de amostra, uso de disco, relacionamentos inferidos
`query`	Execute SQL somente leitura, resultados como JSON
`explain_query`	Planos de execução do PostgreSQL com ANALYZE opcional

Referência completa: isthmus.dev/tools/overview

Documentação

Visite isthmus.dev para a documentação completa:

Instalação — binários pré-compilados, go install, Docker
Configuração — variáveis de ambiente, flags de CLI, referência completa
Configuração de cliente — Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code
Mascaramento de colunas — proteção de PII com redação, hash, parcial, nulo
Mecanismo de políticas — contexto de negócios, filtragem de esquema
Referência de ferramentas — o que cada ferramenta faz e como a IA as usa

Contribuindo

Consulte CONTRIBUTING.md. Você precisará de Go 1.25+ e Docker para testes de integração.

make build        # Build binary
make test         # All tests (needs Docker)
make test-short   # Unit tests only
make lint         # Lint

Licença

Apache 2.0