Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# OpenSearch Server MCP
[OpenSearch MCP server](https://github.com/opensearch-project/opensearch-mcp-server-py) (`opensearch-mcp-server-py`) adalah implementasi open source dari [Model Context Protocol](https://modelcontextprotocol.io) untuk OpenSearch. Ini mengekspos OpenSearch APIs sebagai alat yang asisten AI dan kerangka kerja agen dapat memanggil secara langsung, sehingga Anda dapat mengajukan pertanyaan seperti *“Indeks apa yang ada* di cluster saya?” atau *“Tunjukkan kueri paling lambat dari satu jam terakhir”* dan agen menangani panggilan API atas nama Anda.
Server bekerja dengan domain OpenSearch Layanan terkelola dan koleksi Tanpa OpenSearch Server. Anda dapat menghubungkannya ke pengkodean IDEs (Kiro, Claude Code, Cursor), asisten AI desktop (Claude Desktop), dan kerangka kerja agen (Strands Agents,). LangGraph
## Prasyarat
+ Python 3.10 atau yang lebih baru.
+ [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)(disarankan) atau`pip`.
+ OpenSearch Titik akhir yang dapat dijangkau: domain OpenSearch Layanan, koleksi OpenSearch Tanpa Server, atau klaster yang dikelola sendiri. OpenSearch
+ Kredensil dengan izin untuk memanggil yang ingin OpenSearch APIs Anda ekspos. Untuk kebijakan IAM tentang domain OpenSearch Layanan, lihat. [Kebijakan berbasis identitas](ac.md#ac-types-identity) Untuk kebijakan akses data OpenSearch tanpa server, lihat. [Kontrol akses data untuk Amazon Tanpa OpenSearch Server](serverless-data-access.md)
## Menginstal
Jalankan server dengan `uvx` (tidak diperlukan instalasi) atau instal secara lokal:
```
# Run directly with uvx (recommended – no install step)
uvx opensearch-mcp-server-py
# Or install with pip
pip install opensearch-mcp-server-py
```
Sebagian besar pengguna mengonfigurasi asisten IDE atau AI mereka untuk memulai server secara otomatis. Lihat [Konfigurasikan dalam IDE pengkodean](mcp-server-configure-ide.md) dan [Gunakan dengan kerangka kerja agen](mcp-server-configure-frameworks.md) untuk contoh.
## Autentikasi
Konfigurasikan otentikasi melalui variabel lingkungan (mode cluster tunggal) atau per cluster dalam file konfigurasi YAMM (mode multi-cluster). Server menerapkan metode otentikasi dalam urutan prioritas berikut: no-auth, berbasis header, peran IAM, auth dasar, kunci akses. AWS
**Peran IAM (SiGv4) — direkomendasikan untuk domain Layanan OpenSearch **
```
export OPENSEARCH_URL="{{https://your-domain-endpoint}}"
export AWS_IAM_ARN="arn:aws:iam::{{123456789012}}:role/{{YourOpenSearchRole}}"
export AWS_REGION="{{us-east-1}}"
```
Peran harus memiliki izin untuk memanggil server menggunakan. OpenSearch APIs Lihat [Contoh kebijakan tambahan](ac.md#ac-samples) kebijakan sampel.
**AWS kredensi atau profil**
```
export OPENSEARCH_URL="{{https://your-domain-endpoint}}"
export AWS_REGION="{{us-east-1}}"
export AWS_PROFILE="{{your-aws-profile}}"
```
**OpenSearch Koleksi tanpa server**
Atur `AWS_OPENSEARCH_SERVERLESS=true` sehingga server menandatangani permintaan dengan nama `aoss` layanan, bukan`es`. Pastikan prinsipal diberikan akses melalui kebijakan akses data pada koleksi (lihat[Kontrol akses data untuk Amazon Tanpa OpenSearch Server](serverless-data-access.md)).
```
export OPENSEARCH_URL="{{https://collection-id.us-east-1.aoss.amazonaws.com}}"
export AWS_OPENSEARCH_SERVERLESS="true"
export AWS_REGION="{{us-east-1}}"
export AWS_PROFILE="{{your-aws-profile}}"
```
**Autentikasi dasar**
```
export OPENSEARCH_URL="{{https://your-domain-endpoint}}"
export OPENSEARCH_USERNAME="{{username}}"
export OPENSEARCH_PASSWORD="{{password}}"
```
Jangan menyematkan kata sandi dalam file konfigurasi yang dapat diperiksa ke kontrol sumber. Gunakan manajer rahasia atau lingkungan shell sistem operasi Anda untuk memberikan kredensil.
## Pertimbangan keamanan
Server MCP berjalan dengan kredensil yang Anda berikan. Apa pun yang diizinkan untuk dilakukan oleh kredensi tersebut, asisten AI berpotensi memicu atas nama Anda. Ikuti praktik ini:
+ **Gunakan kredensil hak istimewa paling sedikit.** Buat peran IAM khusus atau OpenSearch pengguna yang tercakup pada indeks dan tindakan yang dibutuhkan agen. Hindari menggunakan kembali kredensi administrator.
+ **Pengembangan dan produksi terpisah.** Arahkan server ke cluster non-produksi untuk eksplorasi. Gunakan multi mode dengan nama cluster eksplisit saat akses produksi diperlukan.
+ **Alat filter.** Nonaktifkan kategori alat yang tidak dibutuhkan alur kerja Anda. Setel `OPENSEARCH_DISABLED_CATEGORIES=core_tools` untuk menonaktifkan set default, atau gunakan `OPENSEARCH_ENABLED_CATEGORIES` untuk mengaktifkan hanya kategori tertentu.
+ **Lindungi kredensil.** Lebih suka AWS profil dan peran IAM daripada kunci akses statis. Jangan pernah memasukkan rahasia ke file konfigurasi di kontrol sumber.
+ **Tinjau keluaran alat.** Respons alat MCP diumpankan kembali ke model bahasa sebagai konteks. Hindari menjalankan server terhadap indeks yang berisi data sensitif yang tidak ingin Anda ekspos ke penyedia AI Anda.
## Pemecahan masalah
**Asisten tidak melihat OpenSearch alat apa pun**
Konfirmasikan file konfigurasi Anda adalah JSON yang valid dan restart klien sepenuhnya. Sebagian besar klien hanya memuat server MCP saat startup.
**Panggilan alat mengembalikan 403 Terlarang**
Kredensi Anda tidak memiliki izin untuk API yang dipanggil alat tersebut. Untuk domain OpenSearch Layanan, tinjau kebijakan akses domain dan kebijakan IAM yang dilampirkan pada peran Anda. Untuk OpenSearch Tanpa Server, tinjau kebijakan akses data koleksi.
**Kesalahan ketidakcocokan tanda tangan dengan Tanpa Server OpenSearch **
Pastikan `AWS_OPENSEARCH_SERVERLESS=true` diatur (atau `is_serverless: true` dalam mode multi). Tanpa itu, server menandatangani dengan nama `es` layanan alih-alih`aoss`.
**Alat yang Anda butuhkan tidak tersedia**
Periksa apakah itu berada dalam kategori non-default dan aktifkan dengan `OPENSEARCH_ENABLED_CATEGORIES` atau `enabled_categories` di konfigurasi YAMM Anda.
Untuk bantuan lebih lanjut, buka masalah di [opensearch-mcp-server-py repositori](https://github.com/opensearch-project/opensearch-mcp-server-py/issues).
## Sumber daya tambahan
+ [opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py)on GitHub — Sumber, masalah, dan catatan rilis.
+ [Panduan Pengguna](https://github.com/opensearch-project/opensearch-mcp-server-py/blob/main/USER_GUIDE.md) — Referensi konfigurasi lengkap termasuk transportasi streaming dan penerapan Kubernetes.
+ [Strands Agents](https://strandsagents.com) — AWS-native agent SDK dengan dukungan MCP bawaan.
+ [LangGraph](https://github.com/langchain-ai/langgraph)— Kerangka orkestrasi tingkat rendah untuk agen stateful.
+ [OpenSearch Keterampilan Agen](opensearch-agent-skills.md)— Koleksi keterampilan pendamping untuk alur kerja yang berfokus pada tugas.