gaussdb-ro-mcp

Servidor MCP somente leitura para Huawei GaussDB (centralizado e distribuído), desenvolvido para agentes de codificação. Proteção de escrita em três camadas, configuração multi-instância, exploração de esquema e execução de SELECT único.

GitHub
1

Documentação

gaussdb-ro-mcp

CI Glama

Servidor MCP somente leitura para GaussDB, voltado para Coding Agents (Claude Code, OpenCode etc.). Baseado no driver Go oficial do GaussDB (versão adaptada do pgx v5, open-source oficial da Huawei Cloud, com código-fonte embutido em third_party/gaussdb-go, suportando build offline), fornece ferramentas de exploração somente leitura do banco via transporte stdio.

Projetado especificamente para ambientes de intranet sem SSL: por padrão sslmode=disable, e o arquivo de configuração suporta o gerenciamento simultâneo de várias instâncias GaussDB.

Garantia de somente leitura (defesa em profundidade, três camadas)

CamadaMecanismoDescrição
1. Validação estática de SQLinternal/guardApenas permite consultas únicas SELECT/WITH: rejeita DML/DDL (incluindo instruções de escrita dentro de CTE), SELECT ... INTO, bloqueio de linha FOR UPDATE/SHARE, múltiplas instruções, funções perigosas (dblink*, set_config, setval, pg_read_file*, pg_terminate_backend, pg_advisory_*, escrita em objetos grandes etc., configurável). A análise léxica ignora corretamente strings, comentários e identificadores entre aspas, evitando falsos positivos
2. Imposição em nível de transaçãointernal/dbTodas as consultas são executadas em transação somente leitura explícita: BEGIN → SET LOCAL TRANSACTION READ ONLY → consulta → COMMIT (rollback em caso de falha). A versão distribuída do GaussDB suporta apenas configuração somente leitura em nível de transação; essa abordagem funciona tanto em instâncias centralizadas/primário-réplica quanto distribuídas; também há SET statement_timeout. Mesmo que a camada 1 seja contornada, o servidor rejeita qualquer escrita dentro da transação (incluindo escritas internas de funções)
3. Recomendação de implantaçãoREADMERecomenda-se usar uma conta de banco com apenas privilégio SELECT (veja abaixo), garantindo privilégio mínimo

Ferramentas MCP fornecidas

FerramentaFunção
test_connectionTeste de conectividade: versão do servidor, banco/usuário atual, status somente leitura, latência; parâmetro opcional instance
list_schemasLista de schemas: número de objetos, comentários; include_system controla se inclui schemas de sistema
list_tablesLista de tabelas/visões: tipo (tabela/visão/visão materializada/tabela particionada/tabela externa), estimativa de linhas, comentários; pode ser filtrado por schema
describe_tableEstrutura da tabela: colunas (tipo/nulável/valor padrão/comentário), chave primária e restrições, todos os índices e definições; visões retornam o SQL de definição; tabelas particionadas retornam a lista de partições (GaussDB pg_partition)
execute_selectExecuta SELECT: aceita apenas um único SELECT/WITH, sujeito a max_rows/limite de tempo, retorna nomes de colunas + dados das linhas + se houve truncamento

Todas as ferramentas aceitam o parâmetro opcional instance para selecionar a fonte de dados; por padrão, usa default_instance.

Instalação

Baixe o binário da plataforma correspondente em Releases (linux-amd64 / linux-arm64 / darwin-arm64 / windows-amd64.exe; outras plataformas ou ambientes de intranet podem compilar manualmente, veja a próxima seção).

Linux:

curl -LO https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-linux-amd64
sudo install -Dm 755 gaussdb-ro-mcp-linux-amd64 /usr/local/bin/gaussdb-ro-mcp
gaussdb-ro-mcp --version

macOS (Apple Silicon):

curl -LO https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-darwin-arm64
sudo install -Dm 755 gaussdb-ro-mcp-darwin-arm64 /usr/local/bin/gaussdb-ro-mcp
gaussdb-ro-mcp --version

Windows (PowerShell; após colocar no diretório do PATH, pode ser chamado diretamente):

Invoke-WebRequest -Uri "https://github.com/gxc/gaussdb-ro-mcp/releases/latest/download/gaussdb-ro-mcp-windows-amd64.exe" -OutFile "gaussdb-ro-mcp.exe"
Move-Item .\gaussdb-ro-mcp.exe "$env:LOCALAPPDATA\Microsoft\WindowsApps\"  # 该目录默认在 PATH 中
gaussdb-ro-mcp --version

Os valores de checksum de cada artefato estão na seção SHA256SUMS.txt da página de Releases.

Build

Requer Go 1.26+ (consistente com go.mod). O código-fonte do driver está embutido em third_party/gaussdb-go (referenciado pela diretiva replace). Em ambiente com rede normal, go build resolve automaticamente as demais dependências; em ambiente totalmente offline, execute go mod vendor em um ambiente com rede e depois leve o diretório vendor/, usando go build -mod=vendor para compilar.

go build -o gaussdb-ro-mcp ./cmd/gaussdb-ro-mcp
sudo install -Dm 755 gaussdb-ro-mcp /usr/local/bin/gaussdb-ro-mcp
gaussdb-ro-mcp --version

Compilação cruzada para outras plataformas (Go puro, basta CGO_ENABLED=0): CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -o ... ./cmd/gaussdb-ro-mcp.

Configuração

Copie gaussdb-ro-mcp.example.yaml para gaussdb-ro-mcp.yaml e edite. Ordem de busca do arquivo de configuração: parâmetro -config > variável de ambiente GAUSSDB_RO_MCP_CONFIG > ./gaussdb-ro-mcp.yaml.

server:
  max_rows: 500          # execute_select 默认行数上限
  max_rows_cap: 10000    # 单次调用可放宽的硬上限
  statement_timeout: 30s
  connect_timeout: 10s

instances:
  - name: prod                    # 实例名称，工具调用时用 instance 参数引用
    host: 192.168.0.10
    port: 8000
    database: postgres
    user: readonly_user
    password: "****"
    sslmode: disable              # 内网非 SSL 默认值
  - name: dev
    dsn: "gaussdb://readonly_user:****@192.168.1.20:5432/appdb?sslmode=disable"

default_instance: prod

Integração com Coding Agents

Claude Code

Opção 1: .mcp.json na raiz do projeto (ou comando claude mcp add):

{
  "mcpServers": {
    "gaussdb-readonly": {
      "command": "/usr/local/bin/gaussdb-ro-mcp",
      "args": ["-config", "/path/to/gaussdb-ro-mcp.yaml"]
    }
  }
}

claude mcp add gaussdb-readonly -- /usr/local/bin/gaussdb-ro-mcp -config /path/to/gaussdb-ro-mcp.yaml

OpenCode

opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gaussdb-readonly": {
      "type": "local",
      "command": ["/usr/local/bin/gaussdb-ro-mcp", "-config", "/path/to/gaussdb-ro-mcp.yaml"]
    }
  }
}

Conta somente leitura no banco (fortemente recomendado)

CREATE USER readonly_user WITH PASSWORD 'your-strong-password';
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;
-- 其他模式按需逐个授权

Mesmo que a conta do banco seja limitada a somente leitura, a validação de SQL e a imposição de sessão deste serviço ainda bloqueiam bloqueio de linha (FOR UPDATE), SELECT INTO, chamadas a funções perigosas, consultas longas etc.

Logs

Todos os logs de execução são enviados para stderr (stdout é o canal do protocolo MCP), incluindo carregamento de configuração, prontidão das fontes de dados, resultado da validação de sessão somente leitura etc., facilitando a depuração nos logs MCP do cliente agente.

Desenvolvimento e testes

go test ./...                       # 单元测试（SQL 校验、配置解析）
GAUSSDB_RO_MCP_TEST_DSN="host=... port=... user=... password=... dbname=... sslmode=disable" \
  go test -count=1 ./...            # 集成测试（需 GaussDB/openGauss 实例）

Você pode usar Docker para iniciar rapidamente uma instância de teste openGauss e carregar dados de teste:

docker run -d --name opengauss-ro-test -e GS_PASSWORD='Gaussdb@123' \
  -p 127.0.0.1:15433:5432 --privileged docker.m.daocloud.io/enmotech/opengauss:latest

go run ./scripts/devseed "host=127.0.0.1 port=15433 user=gaussdb password=Gaussdb@123 dbname=postgres sslmode=disable"

Os testes de integração cobrem: imposição de sessão somente leitura (o servidor rejeita escritas), comportamento de ponta a ponta das 5 ferramentas, teste de fumaça do subprocesso stdio com binário real. Observação: este driver usa o protocolo estendido do GaussDB (3.51), não é possível conectar a PostgreSQL nativo; os testes de integração exigem uma instância real de GaussDB / openGauss.

Estrutura de diretórios

cmd/gaussdb-ro-mcp/     程序入口（stdio MCP 服务器）
internal/config/        YAML 配置：多实例数据源、行数/超时等
internal/guard/         第 1 层防护：SQL 只读静态校验器
internal/db/            多实例连接池 + 第 2 层防护：会话级 READ ONLY 强制、元数据查询
internal/tools/         MCP 工具注册与实现
scripts/devseed/        集成测试数据灌入工具（开发用）
third_party/gaussdb-go/ GaussDB 官方 Go 驱动源码（go.mod replace 引用）

Feedback e contribuições

Issues e Pull Requests são bem-vindos: