AWS OpenSearch MCP, read-only

MCP em Python para investigar domínios do Amazon OpenSearch Service usando profiles AWS locais, incluindo SSO. O servidor foi desenhado para operação segura em CI, QA, produção e telemetry, sem ferramentas de escrita.

O que ele entrega

• Profiles permitidos: ci, qa, prod e telemetry.

• Regiões permitidas por configuração.

• Descoberta de domínios com boto3.

• Acesso ao data plane com AWS Signature Version 4.

• Consultas limitadas por tamanho, timeout e quantidade de documentos.

• Redação de campos com aparência de segredo ou credencial.

• Diagnósticos específicos para shards, flood stage, mappings e timestamps antigos.

• Nenhum endpoint genérico de request e nenhuma ferramenta de escrita.

Related MCP server: mssql-mcp

Tools disponíveis

Pré-requisitos

• Python 3.10 ou superior.

• uv recomendado.

• Profiles AWS já configurados em ~/.aws/config e ~/.aws/credentials.

• Rota de rede até o endpoint. Para domínio VPC-only, a máquina precisa estar na VPN, VPC ou em um túnel apropriado.

Instalação

git clone https://github.com/thiagorchaves/aws-opensearch-mcp-server.git
cd aws-opensearch-mcp-server
cp config.example.yaml config.yaml
uv sync --extra dev

Valide os profiles utilizados:

aws sts get-caller-identity --profile telemetry
aws opensearch list-domain-names --profile telemetry --region us-east-1

Quando o profile usa AWS SSO:

aws sso login --profile telemetry

Rodar manualmente

AWS_OPENSEARCH_MCP_CONFIG="$PWD/config.yaml" \
AWS_SDK_LOAD_CONFIG=1 \
uv run aws-opensearch-mcp

O transporte padrão é stdio, portanto o processo aparentemente fica sem imprimir respostas no terminal. Isso é esperado: ele aguarda um cliente MCP.

Configuração no Kiro

Use o arquivo de usuário ~/.kiro/settings/mcp.json ou o arquivo do workspace .kiro/settings/mcp.json:

{
  "mcpServers": {
    "aws-opensearch-readonly": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/SEU_USUARIO/Projects/aws-opensearch-mcp-server",
        "run",
        "aws-opensearch-mcp"
      ],
      "env": {
        "AWS_OPENSEARCH_MCP_CONFIG": "/home/SEU_USUARIO/Projects/aws-opensearch-mcp-server/config.yaml",
        "AWS_SDK_LOAD_CONFIG": "1",
        "AWS_OPENSEARCH_MCP_LOG_LEVEL": "INFO"
      },
      "timeout": 120000
    }
  }
}

Evite autoApprove no primeiro uso. Depois de revisar os parâmetros e resultados, ferramentas puramente informativas, como get_cluster_health, podem ser aprovadas conforme a política do time.

Testes

uv run pytest -q
uv run ruff check .

Para abrir no MCP Inspector:

uv run mcp dev mcp_server.py

Exemplos de prompts no Kiro

Use o profile telemetry em us-east-1 e liste os domínios OpenSearch disponíveis.

No domínio logs-production, rode diagnose_cluster e explique apenas achados warning ou superiores.

No índice sentinelone-*, verifique o mapping de @timestamp e diagnostique por que os documentos mais novos parecem ser de janeiro.

Liste os 20 maiores índices e verifique quais estão próximos de index.mapping.total_fields.limit.

Encontre shards não alocados e execute explain_unassigned_shard para o primeiro deles. Não faça alterações.

Privacidade dos dados

As respostas das tools entram no contexto do cliente de IA. Restrinja source_fields, evite consultar documentos com dados pessoais desnecessários e use uma identidade com acesso somente aos índices necessários.

IAM mínimo

O arquivo examples/iam-policy.example.json contém uma base. Ajuste conta, domínio e regiões.

A permissão es:ESHttpPost aparece porque APIs read-only como _search e _cluster/allocation/explain usam POST. O MCP não expõe endpoints arbitrários nem operações de escrita, mas a identidade AWS ainda deve seguir privilégio mínimo e, quando disponível, Fine-Grained Access Control do OpenSearch.

Proteções implementadas

• Allowlist de profile e região.

• Validação de domínio, índice e campo.

• Bloqueio de path injection.

• Limite de documentos, bytes de query e resposta.

• Timeout em consultas.

• Bloqueio de script, script_fields, runtime_mappings, rescore e stored_fields nas queries fornecidas pelo modelo.

• Redação recursiva de tokens, senhas, cookies, chaves e segredos.

• Paginação e tamanhos internos de agregações limitados.

• Logs enviados para stderr, preservando o protocolo MCP em stdout.

• Produção e todos os demais profiles permanecem read-only nesta versão.

Evolução sugerida

Uma segunda versão pode adicionar ferramentas de escrita estritamente específicas, sempre em pares preview_* e apply_*, com confirmação explícita e bloqueio por profile. Não adicione uma tool de request HTTP arbitrário, pois ela contornaria todas as proteções deste servidor.

Referências oficiais

• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

• Amazon OpenSearch Service, assinatura SigV4: https://docs.aws.amazon.com/opensearch-service/latest/developerguide/managedomains-signing-service-requests.html

• OpenSearch API: https://docs.opensearch.org/latest/api-reference/

• Kiro MCP configuration: https://kiro.dev/docs/mcp/configuration/