mongo-mcp-simple
# mongo-mcp-simple (`mongo-mcp`)
VS Code (GitHub Copilot Chat ve custom agent'lar) için **MongoDB (4.4 – 8.x)** MCP sunucusu. [sql-mcp-simple](https://github.com/ohankay/sql-mcp-simple) ile aynı yaklaşım: agent'larınız MongoDB işlemlerini mongosh / PowerShell çalıştırmadan, doğrudan bu sunucunun tool'larıyla yapar.
| | |
|---|---|
| Bağlantı | Kullanıcı adı + şifre (SCRAM), **Windows oturumu (Kerberos)**, LDAP, x509 sertifika, kimlik doğrulamasız ya da tam `mongodb://` / `mongodb+srv://` URI; standalone, replica set, sharded, Atlas |
| Okuma | `find`, `aggregate`, `count_documents`, `distinct`; Extended JSON (`{"$oid": ...}`, `{"$date": ...}`), **Türkçe collation** |
| Yazma | `insert_documents`, `update_documents` (operatör veya pipeline, `array_filters`, upsert), `replace_document`, `delete_documents` |
| Transaction | `run_transaction`: birden çok yazma işlemini ya hep ya hiç mantığıyla tek seferde çalıştırır (replica set / sharded) |
| Keşif | `list_databases`, `list_collections`, `infer_schema` (örnekten alan/tip çıkarımı), `list_indexes`, `collection_stats` |
| Yönetim | index oluştur/sil, koleksiyon/view oluştur (validator, capped, timeseries), yeniden adlandır, sil; `run_command` ile her admin komutu (kullanıcı/rol, `collMod`, `explain`, ...); `server_status`, `current_ops`, `kill_op` |
| Güvenlik | Salt okunur profiller, boş filtreyle toplu silme/güncellemede açık onay (`confirm_all`), drop işlemlerinde ad teyidi (`confirm_name`), şifreler hiçbir çıktıda görünmez |
## Kurulum (Windows)
### Hazır paket (önerilen, internet gerekmez)
1. Python'unuza uygun paketi indirip bir klasöre açın:
- **64-bit Python:** [mongo-mcp-simple-windows-x64.zip](https://github.com/ohankay/mongo-mcp-simple/raw/main/release/mongo-mcp-simple-windows-x64.zip)
- **32-bit Python:** [mongo-mcp-simple-windows-x86.zip](https://github.com/ohankay/mongo-mcp-simple/raw/main/release/mongo-mcp-simple-windows-x86.zip)
Python'unuzun kaç bit olduğunu `py -c "import struct; print(struct.calcsize('P')*8)"` gösterir.
2. Klasörü VS Code'da açın, Copilot Chat → **Agent** moduna şunu yazın:
`KURULUM_REHBERI.md dosyasını oku ve "Ajan için kurulum adımları" bölümünü sırayla uygula.`
Paketler her değişiklikte GitHub Actions üzerinde gerçek Windows makinelerde test edilir: 64 ve 32 bit için Python 3.10–3.14'te offline kurulum, kurulum sonrası paket doğrulaması, MCP stdio el sıkışması ve yanlış mimari tespiti.
### Elle kurulum (internet varsa)
```bat
py -m venv %USERPROFILE%\.mongo-mcp
%USERPROFILE%\.mongo-mcp\Scripts\pip install --prefer-binary "mongo-mcp-simple @ git+https://github.com/ohankay/mongo-mcp-simple.git"
```
Bağlantıyı test etmek için:
```bat
set MONGO_MCP_HOST=sunucu:27017
%USERPROFILE%\.mongo-mcp\Scripts\mongo-mcp.exe --check
```
## VS Code'a ekleme
`Ctrl+Shift+P` → **MCP: Open User Configuration**:
```json
{
"inputs": [
{ "type": "promptString", "id": "mongo-password", "description": "MongoDB sifresi", "password": true }
],
"servers": {
"mongo": {
"type": "stdio",
"command": "${userHome}\\.mongo-mcp\\Scripts\\mongo-mcp.exe",
"env": {
"MONGO_MCP_HOST": "mongosrv01:27017",
"MONGO_MCP_USER": "app_user",
"MONGO_MCP_PASSWORD": "${input:mongo-password}",
"MONGO_MCP_AUTH_SOURCE": "admin",
"MONGO_MCP_DATABASE": "AppDb"
}
}
}
}
```
Şifreyi VS Code bir kez sorar ve güvenli deposunda saklar. Hiçbir dosyaya düz metin olarak yazılmaz.
### Birden fazla sunucu (bazısı şifreli, bazısı Windows/Kerberos)
`%USERPROFILE%\.mongo-mcp\connections.json`:
```json
{
"default": "test",
"connections": {
"dev": { "host": "localhost:27017", "database": "AppDb" },
"test": { "host": "mongotest01:27017", "user": "app_user", "password_env": "MONGO_PW_TEST",
"auth_source": "admin", "database": "AppDb" },
"prod": { "host": "m1:27017,m2:27017,m3:27017", "replica_set": "rs0", "user": "report_user",
"password_env": "MONGO_PW_PROD", "database": "AppDb", "readonly": true,
"read_preference": "secondaryPreferred" },
"kurumsal": { "host": "mongoent01.sirket.local:27017", "auth": "windows", "database": "AppDb" }
}
}
```
`mcp.json`: her `password_env` adı için bir `inputs` girdisi ve bir `env` satırı ekleyin:
```json
{
"inputs": [
{ "type": "promptString", "id": "mongo-pw-test", "description": "TEST - app_user sifresi", "password": true },
{ "type": "promptString", "id": "mongo-pw-prod", "description": "PROD - report_user sifresi", "password": true }
],
"servers": {
"mongo": {
"type": "stdio",
"command": "${userHome}\\.mongo-mcp\\Scripts\\mongo-mcp.exe",
"env": {
"MONGO_MCP_CONFIG": "${userHome}\\.mongo-mcp\\connections.json",
"MONGO_PW_TEST": "${input:mongo-pw-test}",
"MONGO_PW_PROD": "${input:mongo-pw-prod}"
}
}
}
}
```
`connections.json` içindeki `password_env` adı ile `mcp.json` `env` anahtarı **harfi harfine aynı** olmalıdır. Eşleşmezse sadece o profil "broken" görünür; diğer profiller çalışmaya devam eder ve hata mesajı `mcp.json`'a eklenmesi gereken satırı söyler.
Copilot'a "**prod** bağlantısında son 10 siparişi getir" demeniz yeterli; agent `list_connections` ile profilleri görüp `connection` parametresini kendisi seçer.
### Custom agent
`.github/agents/mongo-dba.agent.md` (bu repoda örneği var) içinde `tools: ['mongo/*']` yazmanız yeterli.
## Ayarlar
| Env (tek profil) | JSON (çok profil) | Varsayılan | Açıklama |
|---|---|---|---|
| `MONGO_MCP_HOST` | `host` | | `sunucu:27017` veya `m1:27017,m2:27017` |
| `MONGO_MCP_URI` | `uri` / `uri_env` | | `mongodb://` veya `mongodb+srv://` (şifre içeriyorsa `uri_env` ile verin) |
| `MONGO_MCP_AUTH` | `auth` | user varsa `scram`, yoksa `none` | `scram` / `ldap` / `windows` (Kerberos) / `x509` / `none` / `uri` |
| `MONGO_MCP_USER` / `MONGO_MCP_PASSWORD` | `user` / `password_env` | | Kimlik bilgisi |
| `MONGO_MCP_AUTH_SOURCE` | `auth_source` | `admin` (ldap/windows: `$external`) | Kullanıcının tanımlı olduğu veritabanı |
| `MONGO_MCP_DATABASE` | `database` | | Tool'larda `database` verilmezse kullanılan veritabanı |
| `MONGO_MCP_REPLICA_SET` | `replica_set` | | Replica set adı |
| `MONGO_MCP_DIRECT_CONNECTION` | `direct_connection` | | Replica set'te tek üyeye doğrudan bağlan |
| `MONGO_MCP_TLS` | `tls` | `false` | TLS (Atlas için URI zaten içerir) |
| `MONGO_MCP_TLS_INSECURE` | `tls_insecure` | `false` | **Yalnızca test ortamları:** TLS sertifika ve sunucu adı doğrulamasını tamamen kapatır (TLS'i de açar). Trafik şifreli kalır ama sunucunun kimliği doğrulanmaz |
| `MONGO_MCP_TLS_ALLOW_INVALID_CERTIFICATES` | `tls_allow_invalid_certificates` | `false` | Yalnızca sertifika zinciri doğrulamasını kapatır (test) |
| `MONGO_MCP_TLS_ALLOW_INVALID_HOSTNAMES` | `tls_allow_invalid_hostnames` | `false` | Yalnızca sunucu adı kontrolünü kapatır, sertifika doğrulaması sürer (test) |
| `MONGO_MCP_TLS_CA_FILE` / `MONGO_MCP_TLS_CERTIFICATE_KEY_FILE` | `tls_ca_file` / `tls_certificate_key_file` | | CA dosyası / x509 istemci sertifikası |
| `MONGO_MCP_READ_PREFERENCE` | `read_preference` | | `primary`, `secondaryPreferred`, ... |
| `MONGO_MCP_READONLY` | `readonly` | `false` | Yazma tool'larını ve yazan komutları engeller |
| `MONGO_MCP_MAX_DOCS` | `max_docs` | `100` | Bir sonuçta dönen en fazla doküman (agent bağlamı şişmesin diye) |
| `MONGO_MCP_MAX_TIME_MS` | `max_time_ms` | `60000` | Sorgu zaman aşımı |
| `MONGO_MCP_SERVER_SELECTION_TIMEOUT_MS` | `server_selection_timeout_ms` | `10000` | Sunucuya ulaşma zaman aşımı |
| `MONGO_MCP_FALLBACK_DIRECT` | `fallback_direct` | `true` | Replica set bütün olarak kullanılamazsa (ör. üyeler kendini iç ağ adı / farklı port ile bildiriyorsa), adresteki sunucuları sırayla doğrudan dener ve ilk cevap verenle devam eder |
| `MONGO_MCP_SERVER_MONITORING_MODE` | `server_monitoring_mode` | `poll` | Sürücünün sunucu izleme yöntemi. `poll`, uzun süre açık kalan bağlantıları kesen firewall/VPN ortamlarında güvenli seçenektir; `stream` sürücünün kendi varsayılanıdır |
| `MONGO_MCP_CONFIG` | | | Çoklu profil JSON dosyası |
**Windows oturumu (Kerberos):** `auth: "windows"` MongoDB **Enterprise** sunucularında Kerberos yapılandırılmışsa çalışır. Principal, Windows oturumundan (`KULLANICI@DOMAIN`) otomatik alınır, şifre gerekmez. Domain dışı bir bilgisayarda `user` alanına principal'ı yazın.
## Bilinmesi gerekenler
* **Türkçe arama:** regex `$options: "i"`, `İ`/`i` ve `I`/`ı` harflerini eşlemez. Büyük/küçük harf duyarsız Türkçe arama için `collation: {"locale": "tr", "strength": 2}` kullanın (`find`, `aggregate`, `count_documents`, `distinct`, `update_documents`, `delete_documents`). Türkçede `ş`, `ğ`, `ç`, `ö`, `ü` ayrı harflerdir; `AYSE`, `Ayşe` ile eşleşmez.
* **Özel tipler:** Sonuçlar relaxed Extended JSON döner (`{"$oid": "..."}`, `{"$date": "..."}`, `{"$numberDecimal": "..."}`). Bu değerler sonraki sorgularda filtre olarak aynen kullanılabilir.
* MongoDB'nin kendi `$toUpper` / `$toLower` operatörleri sadece ASCII harfleri dönüştürür ("Ayşe" → "AYşE").
* **Replica set'e erişim:** Sürücü önce normal replica set bağlantısını dener; profilin okuma tercihine (`readPreference`) uygun en az bir üyeye ulaşabildiği sürece erişilemeyen üyeleri atlar. Replica set üyeleri kendini bilgisayarınızdan erişilemeyen adreslerle bildiriyorsa (iç ağ adları, `localhost`, farklı port; Windows'ta `WinError 10061`), bağlantı adresindeki sunucular **sırayla doğrudan** denenir ve ilk cevap verenle devam edilir. Hangi sunucuya düşüldüğü `test_connection` ve `list_connections` çıktısında `direct_fallback` olarak görünür. Düşülen sunucu secondary ise okumalar çalışır, yazmalar sunucu tarafından reddedilir.
* **Ağ kaynaklı hatalar** (`_OperationCancelled`, `Could not reach`, `Lost the connection`): hata yanıtında tahmin değil kanıt döner:
* `stage`: hatanın aşaması: `connect` (bağlantı/replica set keşfi) ya da `operation` (komut çalışırken).
* `servers`: her sunucunun sürücü tarafından görülen durumu, gecikmesi ve son hatası.
* `events`: hatadan kısa süre önce kaydedilen sürücü olayları (zaman ve sunucu adresiyle): `heartbeat_failed`, `server_changed`, `pool_cleared` (`interrupted_in_use_connections` ile), `connection_check_out_failed`, `command_failed`. Komut içeriği ve kimlik bilgisi kaydedilmez.
* `_OperationCancelled`: sürücü, kullandığı sunucunun bağlantı havuzunu işlem sürerken temizlediği için işlemi iptal etti demektir; nedeni `events` içindeki `heartbeat_failed` / `pool_cleared` kayıtlarında görülür.
* **TLS doğrulamasını kapatma (yalnızca test):** profile `"tls_insecure": true` ekleyin (ortam değişkeni `MONGO_MCP_TLS_INSECURE=true`, ya da URI sonuna `&tls=true&tlsInsecure=true`). TLS'i de açar; URI'deki diğer `tlsAllowInvalid*` seçenekleriyle çakışmaz.
* **TLS / SSL sorunları:** TLS kaynaklı bir bağlantı hatasında mesaj `TLS/SSL problem (sunucu:port): ...` ile başlar ve yanıtta `tls` alanı döner:
* `problem`: `untrusted_certificate` (CA tanınmıyor / self-signed), `hostname_mismatch`, `certificate_expired`, `certificate_not_yet_valid`, `weak_certificate`, `client_certificate_required`, `client_certificate_rejected`, `client_certificate_file`, `server_requires_tls` (profilde TLS yok ama sunucu istiyor), `server_not_tls` (profilde TLS var ama sunucu kullanmıyor), `protocol_mismatch`, `handshake_failed`.
* `server`, `summary`, `driver_detail` (OpenSSL'in özgün mesajı), `how_to_fix` (yapılacaklar), `settings` (profilin etkin TLS ayarları).
* `evidence`: sunucuya kimlik bilgisi göndermeden yapılan tek bir TLS el sıkışmasının sonucu: sunucu TLS konuşuyor mu, protokol, şifre takımı ve sunucu sertifikası (subject, issuer, sertifikadaki adlar, geçerlilik tarihleri, süresi dolmuş mu, SHA-256 parmak izi).
* Sertifika sorunlarında `test_only_workaround`: `tls_insecure` ile nasıl geçileceği. Tüm sunucular TLS hatası veriyorsa doğrudan bağlanma denemesi (direct fallback) yapılmaz, hata hemen döner.
* `tls_insecure` / `tls_allow_invalid_*` açık profillerde `test_connection` çıktısında `tls.verification` ve `tls.warning`, `list_connections` çıktısında `tls_warning` görünür.
* **Yeniden deneme politikası:** Okuma araçları (`find`, `aggregate`, `count_documents`, `list_*` ...) ağ hatası alırsa istemci kapatılıp **yeni bir istemciyle bir kez** tekrar denenir; başarılı olursa yanıtta `retried_after` alanı ilk hatayı ve olaylarını gösterir. Yazma araçları ve `run_command` **asla otomatik tekrarlanmaz**: komut çalışırken bağlantı koptuysa yanıtta `write_outcome: "unknown"` döner, yazmanın uygulanıp uygulanmadığını tekrar etmeden önce kontrol edin. Her ağ hatasından sonra istemci sıfırlanır, aynı aracı tekrar çağırmak yeni bağlantıyla başlar.
* **Okuma tercihi:** `list_databases`, `list_collections`, `collection_stats`, `list_indexes` artık profilin `readPreference` ayarına uyar (eskiden primary'ye gidiyordu); `secondaryPreferred` profilinde primary erişilemezken de çalışırlar.
* **Çalışan sürümü doğrulama:** `test_connection` çıktısındaki `runtime` alanı çalışan MCP sürecinin sürümünü, `pid`'ini, başlama zamanını, Python sürümü/bitliğini ve modül yolunu gösterir. Güncellemeden sonra eski davranış görüyorsanız VS Code'da MCP sunucusunu yeniden başlatın ("MCP: List Servers" → mongo → Restart) ve `runtime.mongo_mcp` sürümünü kontrol edin. Ayrıca `members_seen` ve `primary_reachable` alanları replica set'te hangi üyelerin görüldüğünü gösterir.
* `run_transaction` replica set veya sharded cluster gerektirir; standalone sunucuda açık bir hata döner ve hiçbir şey yazılmaz.
* Sunucu tarafı notu: MongoDB **8.0.x**, Linux çekirdeği 6.19 ve üzerinde başlamayı reddeder ([SERVER-121912](https://jira.mongodb.org/browse/SERVER-121912)). 8.2, 7.0 ve öncesi etkilenmez. Bu MCP'yi değil, MongoDB sunucusunun kurulu olduğu makineyi ilgilendirir.
## Geliştirme ve testler
```bash
pip install -e ".[dev]"
docker compose -f tests/docker-compose.yml up -d
docker exec mongo-rs mongosh --port 27019 --quiet --eval "rs.initiate({_id:'rs0',members:[{_id:0,host:'localhost:27019'}]})"
export MONGO_MCP_TEST_TARGETS="mongo82=mongodb://root:Str0ng%21Pass@localhost:27082/;mongo70=mongodb://root:Str0ng%21Pass@localhost:27070/;mongo44=mongodb://root:Str0ng%21Pass@localhost:27044/"
export MONGO_MCP_TEST_RS="mongodb://localhost:27019/?replicaSet=rs0"
pytest -v
```
Test kapsamı:
* **Unit:** konfigürasyon doğrulama ve hata mesajları, bozuk profilin diğerlerini etkilememesi, her kimlik doğrulama tipi için istemci ayarları (Kerberos principal dahil), Extended JSON, salt okunur koruması, şablonlar ve `install.cmd`.
* **Entegrasyon:** MongoDB **8.2, 8.0, 7.0 ve 4.4** (kimlik doğrulamalı) ve replica set üzerinde CRUD, Türkçe collation, pipeline update, `array_filters`, duplicate key ve kısmi bulk hata, limit ve kesme, zaman aşımı, aggregate ve `$out`, şema çıkarımı, view, validator, capped, index'ler, `run_command`, düşük yetkili kullanıcıyla yetki hataları, `kill_op`, salt okunur profil, eşzamanlı çağrılar, transaction commit/rollback.
* **Uçtan uca:** `python -m mongo_mcp` gerçek MCP stdio protokolüyle (VS Code'un yaptığı gibi) başlatılır; bozuk profil, çok profilli şifre akışı, transaction ve `--check` CLI'ı test edilir.
## Lisans
MIT
TDQS
Scored across 28 tools
Most tools target a clearly distinct resource and action (find vs aggregate vs count_documents vs distinct, list vs create vs drop for collections/indexes). The main overlap is the generic run_command, which can duplicate server_status, current_ops, kill_op, create_index, and other administrative operations; count_documents vs collection_stats is also mildly overlapping. Descriptions still make the intended dedicated tool clear in most cases.
The dominant convention is verb_noun snake_case (list_connections, insert_documents, create_index, drop_collection). There are minor deviations: single-verb tools (find, aggregate, distinct) and noun-based tools (collection_stats, server_status, current_ops). These deviations are readable and predictable, not chaotic.
The server exposes 28 tools, which is above the 25+ threshold for 'too many' under the rubric. The breadth of MongoDB administration explains many of them, but the surface is heavy and could be consolidated in places (e.g. connection management, collection/index lifecycle, and generic run_command coverage).
The surface covers connection management, database/collection/index lifecycle, CRUD, aggregation, counts, distinct values, schema inference, transactions, server health, running ops, and a generic run_command escape hatch. Core MongoDB workflows have no obvious dead ends; less common operations like user management or collMod are reachable through run_command.