YugabyteDB MCP Server

Permite que LLMs interajam diretamente com um banco de dados YugabyteDB.

Documentação

Servidor MCP YugabyteDB

Um servidor MCP para YugabyteDB e PostgreSQL — permite que LLMs (Claude Desktop, Cursor, Windsurf, etc.) resumam esquemas, executem consultas somente leitura e executem instruções de escrita por trás de uma camada de proteção configurável.

Recursos

summarize_database — lista tabelas com colunas e contagens de linhas para um esquema (somente leitura)
run_read_only_query — executa um SELECT sob BEGIN READ ONLY; resultados retornados como JSON (somente leitura)
run_write_query — INSERT/UPDATE/DELETE/MERGE/TRUNCATE/DDL controlados por uma lista de bloqueio de proteção (destrutivo, desabilitado por padrão — habilite com --enable-write-query ou YB_MCP_ENABLE_WRITE_QUERY=true)

Defesa em profundidade: a ferramenta de escrita é anotada com destructiveHint: true, então o Claude Desktop exibe um prompt de confirmação antes de cada chamada, mesmo quando as proteções permitiriam a instrução.

OAuth opcional (AWS Cognito) e validação de cabeçalho Origin para implantações remotas auto-hospedadas.

Pré-requisitos

Python 3.10+
uv (recomendado) ou pip
Um banco de dados YugabyteDB ou PostgreSQL acessível
Um cliente MCP (Claude Desktop, Cursor, Windsurf, etc.)

Instalação

Três opções de instalação, aproximadamente na ordem em que os usuários finais as utilizarão:

# uvx — no install at all; fetches and runs on demand. Handy for one-off use
# and also the form the MCPB Desktop extension uses internally.
uvx yugabytedb-mcp-server --help

# pipx — installs to an isolated venv, puts the script on $PATH.
pipx install yugabytedb-mcp-server

# uv tool — same idea, uv-managed.
uv tool install yugabytedb-mcp-server

# pip — system-level or current-venv install.
pip install yugabytedb-mcp-server

Após qualquer uma das instalações persistentes (pipx / uv tool / pip), verifique com:

yugabytedb-mcp --help
# or, equivalently:
yugabytedb-mcp-server --help

Ambos os scripts de console estão registrados e apontam para o mesmo ponto de entrada — yugabytedb-mcp é a forma curta, yugabytedb-mcp-server corresponde ao nome do pacote e é o que uvx resolve por padrão.

Nota de pré-lançamento: enquanto v2 estiver em candidato a lançamento (ex.: 2.0.0rc2), as instalações padrão não o selecionarão. Por enquanto, instale com uma versão explícita (pipx install yugabytedb-mcp-server==2.0.0rc2) ou com --pip-args='--pre'. Isso desaparece assim que 2.0.0 estável for publicado.

Para desenvolvimento a partir do código-fonte, consulte Desenvolvimento abaixo.

Configuração

Variável de Ambiente	Flag CLI	Obrigatório	Descrição
`YUGABYTEDB_URL`	`--yugabytedb-url`	Sim	String de conexão libpq (ex.: `host=… port=5433 dbname=… user=… password=…`).
`YB_MCP_TRANSPORT`	`--transport`	Não	`stdio` (padrão) ou `http`.
`YB_MCP_STATELESS_HTTP`	`--stateless-http`	Não	`true` habilita Streamable-HTTP sem estado — necessário para implantações auto-hospedadas com múltiplas réplicas.
`YB_MCP_REQUIRE_WHERE_ON_UPDATE`	`--require-where-on-update`	Não	Rejeita UPDATE sem cláusula WHERE. Padrão `false`.
`YB_MCP_REQUIRE_WHERE_ON_DELETE`	`--require-where-on-delete`	Não	Rejeita DELETE sem cláusula WHERE. Padrão `false`.
`YB_MCP_ENABLE_WRITE_QUERY`	`--enable-write-query`	Não	Habilita a ferramenta `run_write_query`. Padrão `false` (ferramenta de escrita desabilitada).
`MCP_AUTH_PROVIDER`	`--mcp-auth-provider`	Não	`cognito` ou `oidc`. Deixe não definido para desabilitar autenticação. Configuração completa OIDC/Cognito + mapeamento de identidade por usuário está documentada em `OIDC.md`.
`MCP_HOST`	`--host`	Não	Host de bind para transporte HTTP. Padrão `127.0.0.1` (loopback). Defina como `0.0.0.0` para expor em todas as interfaces — autenticação torna-se obrigatória nesse caso (veja `MCP_AUTH_PROVIDER`).
`MCP_BASE_URL`	—	Quando autenticação habilitada	URL base pública onde o servidor é acessível (ex.: `https://mcp.example.com`).
`MCP_ALLOWED_ORIGINS`	—	Não	Lista de permissões separada por vírgulas de valores Origin para defesa contra DNS-rebinding. Insensível a maiúsculas/minúsculas (RFC 6454). Padrão `MCP_BASE_URL`.
`MCP_ALLOW_UNAUTHENTICATED`	—	Não	Saída de emergência para executar modo HTTP em host não-loopback sem autenticação. Apenas desenvolvimento; o log de inicialização exibe um WARNING proeminente.
`YB_LOG_LEVEL`	—	Não	Nível de log para a família de loggers `yugabytedb-mcp` (padrão `INFO`).
`YB_AWS_SSL_ROOT_CERT_SECRET_ARN`	`--yb-aws-ssl-root-cert-secret-arn`	Não	ARN de um segredo do AWS Secrets Manager contendo o certificado raiz TLS do YugabyteDB.
`YB_AWS_SSL_ROOT_CERT_KEY`	`--yb-aws-ssl-root-cert-key`	Não	Chave JSON dentro do segredo quando ele armazena múltiplos certificados.
`YB_AWS_SSL_ROOT_CERT_SECRET_REGION`	`--yb-aws-ssl-root-cert-secret-region`	Não	Região AWS do segredo.
`YB_SSL_ROOT_CERT_PATH`	`--yb-ssl-root-cert-path`	Não	Onde escrever o certificado obtido. Padrão `/tmp/yb-root.crt`.

Para autenticação OIDC/Cognito, mapeamento de SET ROLE por usuário, o formato do arquivo de mapa de identidade e o atalho /auth/login — veja OIDC.md.

Um modelo inicial está em .env.example.

Início rápido — Claude Desktop

Duas maneiras de configurar. A primeira usa uvx e não requer instalação alguma — apenas uv. A segunda assume que você já executou pipx install (ou equivalente) e tem o script yugabytedb-mcp no $PATH.

Opção 1 — via uvx (sem instalação):

{
  "mcpServers": {
    "yugabytedb": {
      "command": "uvx",
      "args": ["yugabytedb-mcp-server"],
      "env": {
        "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…"
      }
    }
  }
}

Opção 2 — via script instalado:

Após pipx install yugabytedb-mcp-server (ou uv tool install …):

{
  "mcpServers": {
    "yugabytedb": {
      "command": "yugabytedb-mcp",
      "env": {
        "YUGABYTEDB_URL": "host=… port=5433 dbname=… user=… password=…"
      }
    }
  }
}

Localizações de claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Reinicie o Claude Desktop. As três ferramentas aparecerão com títulos e selos de dica (ícones somente leitura nas ferramentas de leitura, um prompt de confirmação antes de cada chamada run_write_query).

Enquanto 2.0.0rc2 é a única versão publicada, o trecho uvx precisa de ["yugabytedb-mcp-server@2.0.0rc2"] nos argumentos (ou ["--pre", "yugabytedb-mcp-server"]). Drop the explicit version once 2.0.0 estável for lançado.

Outros Clientes MCP

A mesma abordagem funciona com Cursor (Configurações → MCP → Adicionar novo servidor MCP global) e Windsurf (Configurações → Cascade → Servidores MCP → Adicionar servidor personalizado) — use a forma uvx ou a forma de script instalado acima.

Para MCP Inspector contra um servidor em modo HTTP:

YUGABYTEDB_URL="…" yugabytedb-mcp --transport http
# in another shell:
npx @modelcontextprotocol/inspector
# In the GUI: URL http://localhost:8000/mcp, transport Streamable-HTTP

Ferramentas

Ferramenta	Título	Dicas	O que faz
`summarize_database(schema='public')`	"Resumir esquema do banco de dados e contagens de linhas"	`readOnlyHint: true`	Lista tabelas em `schema` com colunas e contagens de linhas
`run_read_only_query(query)`	"Executar consulta SQL somente leitura"	`readOnlyHint: true`	Envolve a consulta em `BEGIN READ ONLY` e retorna linhas como JSON
`run_write_query(query)`	"Executar consulta SQL de escrita (com proteções)"	`destructiveHint: true`	Valida a consulta contra a lista de bloqueio de proteção e então executa. Desabilitada por padrão — requer `--enable-write-query`.

Proteções para `run_write_query`

As seguintes classes de instruções são rejeitadas antes da execução:

DROP DATABASE/SCHEMA, ALTER DATABASE, CREATE DATABASE
Operações de papel/privilegios: GRANT, REVOKE, CREATE/ALTER/DROP ROLE, CREATE/ALTER/DROP USER
Código armazenado que pode executar sob o proprietário (SECURITY DEFINER): CREATE FUNCTION, CREATE PROCEDURE, ALTER FUNCTION, ALTER PROCEDURE
Sistema de arquivos / execução de código: COPY TO/FROM, LOAD, DO $$ … $$ anônimo, CREATE EXTENSION
Configuração do servidor: ALTER SYSTEM, RESET ALL
Funções internas perigosas: pg_sleep, pg_read_file, pg_write_file, lo_import, lo_export, dblink
Isolamento de esquema: SET search_path, CREATE SCHEMA
Consultas multi-instruções (qualquer coisa com ponto e vírgula separador)
Meta-comandos psql (\c, \d, \!)
Opcionalmente UPDATE / DELETE sem cláusula WHERE

O tempo de execução de INSERT / UPDATE / DELETE / DDL é limitado por YB_MCP_STATEMENT_TIMEOUT_MS (SET LOCAL statement_timeout aplicado a cada escrita) — um INSERT … SELECT descontrolado ou INSERT … VALUES amplo é encerrado pelo banco, não por um limite estático de linhas.

CREATE TABLE … AS SELECT e SELECT … INTO são cópias de linhas ilimitadas estruturalmente semelhantes, mas são intencionalmente permitidas — são a maneira comum de materializar um snapshot a partir de uma consulta.

Esta lista é de melhor esforço, não exaustiva. destructiveHint: true é a segunda linha de defesa.

Modo remoto auto-hospedado

Para implantações multiusuário ou compartilhadas, execute o servidor como Streamable HTTP atrás de um proxy reverso com TLS, com OAuth Cognito (ou OIDC genérico) controlando o acesso. A configuração completa — configuração do provedor, mapeamento de SET ROLE por usuário, o formato do arquivo de mapa de identidade, o atalho /auth/login e orientações de segurança — está em OIDC.md.

Seguro por padrão: desde a correção, o modo HTTP vincula 127.0.0.1 por padrão e recusa iniciar quando ambos são verdadeiros:

O host de bind é não-loopback (MCP_HOST definido como 0.0.0.0 ou um endereço específico)
Nenhum provedor de autenticação está configurado (MCP_AUTH_PROVIDER não definido)

Para uma implantação compartilhada / em rede, defina ambos MCP_HOST=0.0.0.0 e MCP_AUTH_PROVIDER:

export MCP_HOST=0.0.0.0                # expose beyond loopback (default: 127.0.0.1)
export MCP_AUTH_PROVIDER=cognito
export MCP_BASE_URL=https://mcp.example.com
export COGNITO_USER_POOL_ID=us-west-2_XXXXXXXX
export COGNITO_AWS_REGION=us-west-2
export COGNITO_CLIENT_ID=…
export COGNITO_CLIENT_SECRET=…
export YUGABYTEDB_URL=…
export MCP_ALLOWED_ORIGINS=https://mcp.example.com,https://claude.ai

yugabytedb-mcp --transport http --stateless-http

Para uso não autenticado apenas em desenvolvimento em 0.0.0.0, defina MCP_ALLOW_UNAUTHENTICATED=true — o servidor inicia com um WARNING proeminente. Não use isso em produção.

Comportamento:

Requisições para /mcp sem um token Bearer válido retornam 401.
Requisições com cabeçalho Origin não permitido retornam 403 (defesa contra DNS-rebinding).
/ping é não autenticado e adequado para sondas de liveness.
/auth/login expõe um atalho de email+senha Cognito → token (detalhes em OIDC.md).
--stateless-http é necessário para implantações com múltiplas réplicas — sem ele, o estado da sessão MCP vive na memória do processo e o balanceamento de carga round-robin quebra as sessões.

AWS Secrets Manager para certificados TLS

Se o certificado raiz TLS do seu banco de dados estiver armazenado no AWS Secrets Manager, o servidor pode buscá-lo e usá-lo automaticamente. PEM em texto simples é suportado; bundles com chave JSON também (defina YB_AWS_SSL_ROOT_CERT_KEY para selecionar um).

yugabytedb-mcp \
  --yugabytedb-url "host=… port=5433 dbname=… user=… password=… sslmode=verify-full" \
  --yb-aws-ssl-root-cert-secret-arn arn:aws:secretsmanager:us-east-1:…:secret:my-cert \
  --yb-aws-ssl-root-cert-secret-region us-east-1

Docker

docker build -t mcp/yugabytedb .
docker run -p 8000:8000 -e YUGABYTEDB_URL="…" mcp/yugabytedb yugabytedb-mcp --transport http

Segurança

Todo SQL é executado por meio de consultas parametrizadas; a entrada do usuário nunca é interpolada em strings de instruções.
A ferramenta de escrita está desabilitada por padrão — deve ser explicitamente habilitada com --enable-write-query.
A lista de proteção da ferramenta de escrita (acima) bloqueia as classes de instruções de maior risco.
destructiveHint: true garante que o Claude Desktop exiba uma confirmação por chamada para operações de escrita.
Quando a autenticação OIDC está ativa, SET ROLE por usuário impõe limites de privilégios no nível do banco por chamador. Nomes de papéis são citados com segurança com psycopg.sql.Identifier.
O transporte HTTP requer um token Bearer válido quando MCP_AUTH_PROVIDER está configurado.
O transporte HTTP valida o cabeçalho Origin contra MCP_ALLOWED_ORIGINS (padrão MCP_BASE_URL).
HTTPS é responsabilidade do operador — termine o TLS em um proxy reverso (nginx, ALB, etc.) na frente do servidor.
Execute com um papel de banco de privilégio mínimo (papel somente leitura para implantações apenas com run_read_only_query; caso contrário, um papel com escopo nos esquemas de destino, sem superusuário).

Relate problemas de segurança em particular para support@yugabyte.com — por favor, não abra issues públicas no GitHub para vulnerabilidades.

Política de Privacidade

A política de privacidade da Yugabyte se aplica: https://www.yugabyte.com/privacy-policy/

Este servidor MCP não transmite telemetria. Todo acesso ao banco de dados permanece entre o Claude (seu cliente MCP) e sua instância YugabyteDB por meio da string de conexão que você fornece. O servidor registra logs localmente no stderr (controlado por YB_LOG_LEVEL) — nenhuma agregação remota de logs está integrada.

Desenvolvimento

git clone git@github.com:yugabyte/yugabytedb-mcp-server.git
cd yugabytedb-mcp-server
uv sync
uv run yugabytedb-mcp --help

Nota: não existe mais um src/server.py que você possa executar diretamente. O layout do pacote foi reorganizado para distribuição no PyPI (ponto de entrada + namespace), então os módulos agora vivem sob src/yugabytedb_mcp_server/. Sempre invoque por meio do script de console yugabytedb-mcp (registrado por uv sync / pip install) — executar o arquivo do módulo com python pularia a maquinaria de importação do pacote e quebraria as importações relativas.

Comandos equivalentes:

uv run yugabytedb-mcp                 # uses the console script
uv run python -m yugabytedb_mcp_server # uses the __main__.py shim

Testando o conector localmente no Claude Desktop

Dois caminhos, dependendo de quão próximo da experiência de instalação de produção você quer chegar:

Mais rápido — sem build MCPB, apenas aponte o Claude Desktop para o ponto de entrada local. Após uv sync, o script yugabytedb-mcp está no seu $PATH (via o venv ativo). Adicione isso ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "yugabytedb-dev": {
      "command": "/absolute/path/to/repo/.venv/bin/yugabytedb-mcp",
      "env": {
        "YUGABYTEDB_URL": "host=localhost port=5433 dbname=yugabyte user=yugabyte password=yugabyte",
        "YB_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Reinicie o Claude Desktop. Use ~/Library/Logs/Claude/mcp-server-yugabytedb-dev.log (macOS) para inspecionar a saída de depuração. Isso pula o empacotamento MCPB inteiramente e é o loop certo para iterar no código das ferramentas. Mais próximo da produção — crie um .mcpb e arraste-o para o Claude Desktop. Requer a CLI MCPB:

npm install -g @modelcontextprotocol/mcpb-cli   # one-time
mcpb validate manifest.json                      # static check
mcpb pack .                                      # produces yugabytedb-mcp-server-<version>.mcpb

Arraste o .mcpb resultante para o Claude Desktop — a interface do instalador do conector cuida do resto, solicitando os valores de user_config definidos em manifest.json. A rota .mcpb é a mais próxima do que os revisores irão exercitar. Nota: o mcp_config do manifesto executa uvx yugabytedb-mcp-server, que busca o pacote no PyPI no primeiro lançamento. Certifique-se de que a versão referenciada pelo seu .mcpb esteja publicada antes de compartilhar o pacote.

Testes

# unit tests (no DB, no network)
uv run pytest tests/test_guardrails.py tests/test_auth.py tests/test_identity_mapping.py

# integration tests (require a reachable Postgres-compatible DB)
YUGABYTEDB_URL="host=… port=… …" uv run pytest tests/

Consulte tests/README.md para a tabela de cobertura e a receita manual de teste de fumaça com Cognito.

Solução de problemas

spawn yugabytedb-mcp ENOENT do Claude Desktop → garanta que o diretório de instalação esteja no PATH que o Claude Desktop enxerga; pipx ensurepath ou crie um link simbólico para o ponto de entrada em /usr/local/bin.
A lista de ferramentas está vazia no cliente MCP → reinicie o cliente; verifique a saída de YB_LOG_LEVEL=DEBUG para erros de conexão durante o ciclo de vida.
"Transação inválida ou expirada" / "Cliente não registrado" no modo HTTP+OAuth com múltiplas réplicas → consulte a seção remota auto-hospedada; --stateless-http é obrigatório para múltiplas réplicas.

Licença

Licença Apache 2.0.