MongoDB Atlas Tool Plugin for Dify

A Tool-type Dify plugin that lets Chatflow, Workflow, and Agent applications query, search, and write documents in MongoDB Atlas directly from a workflow node or agent tool call.

Companion plugins:

• Use the Voyage AI plugin to generate real vector embeddings and pipe them into the Vector Search tool's Query Vector field.
• Use the MongoDB Atlas Datasource plugin to feed Atlas collections into the Dify Knowledge Base / RAG pipeline.

---

Features

Tool	Description
Find Documents	Query a collection with an optional MongoDB filter and projection
Full-Text Search	Atlas $search full-text search (requires an Atlas Search index)
Vector Search	Atlas $vectorSearch ANN search — accepts a pre-computed embedding vector
Aggregate	Run any raw aggregation pipeline
Insert Document	Insert a single document and get back its _id
Update Documents	updateMany with a filter + update operator JSON
Delete Documents	deleteMany with a filter JSON

---

Prerequisites

• A MongoDB Atlas cluster (M0 free tier is sufficient for testing)
• A connection string: mongodb+srv://<user>:<password>@<cluster>.mongodb.net/
• For Full-Text Search: an Atlas Search index on the target collection
• For Vector Search: an Atlas Vector Search index on the target collection

---

Installation

From Dify Marketplace

Search for MongoDB Atlas Tool in the Dify Plugin Marketplace and click Install.

Local / Debug Install

1. Clone or download this repository.
2. Copy .env.example to .env and fill in your Dify remote debug URL and key.
3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the plugin:

   python -m main
   

5. The plugin will appear in your Dify workspace under Plugins.

Package for distribution

dify plugin package ./mongodb_atlas_tool

---

Configuration

When installing the plugin, you will be prompted for:

Credential	Required	Description
Connection String	✅	mongodb+srv://user:password@cluster.mongodb.net/

---

Tool Reference

Find Documents

Query documents using a MongoDB filter.

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database to query
collection_name	string	✅	llm	Collection to query
filter_json	string	❌	llm	JSON filter, e.g. {"status": "active"}
projection_json	string	❌	llm	JSON projection, e.g. {"name": 1, "_id": 0}
limit	number	❌	form	Max documents to return (default 20, max 1000)

Output (JSON): Each document is yielded as its own JSON message — json[0] is the first document, json[1] is the second, etc. Results are directly iterable in Dify's Iterate/Loop nodes.

---

Full-Text Search

Atlas $search across all text fields. Requires an Atlas Search index.

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database
collection_name	string	✅	llm	Collection
query	string	✅	llm	Search query string
index_name	string	❌	form	Atlas Search index name (default "default")
limit	number	❌	form	Max results (default 20)

Output (JSON): Each document is yielded as its own JSON message — directly iterable.
Output (text): A JSON array of stringified documents, pipeable to the Rerank tool's documents parameter.
Each document includes a _search_score field.

---

Vector Search

Atlas $vectorSearch approximate nearest-neighbour search. Requires an Atlas Vector Search index.

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database
collection_name	string	✅	llm	Collection
query_vector	string	✅*	llm	Pre-computed embedding as a JSON float array
query_text	string	✅*	llm	Fallback text query (uses placeholder zero-vector — use Voyage AI plugin for real embeddings)
vector_index_name	string	❌	form	Vector Search index name (default "vector_index")
vector_field	string	❌	form	Embedding field name (default "embedding")
num_candidates	number	❌	form	ANN candidates (default 150, must be ≥ limit)
limit	number	❌	form	Max results (default 20)

* Provide either query_vector or query_text.

Tip: Use the Voyage AI plugin's Embed Text tool to generate query_vector. The output text variable can be piped directly into query_vector — the plugin automatically handles the array format.

Output (JSON): Each document is yielded as its own JSON message — directly iterable.
Output (text): A JSON array of stringified documents, pipeable to the Rerank tool's documents parameter.
Each document includes a _vector_score field. The embedding field is excluded from results.

---

Aggregate

Run a raw MongoDB aggregation pipeline.

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database
collection_name	string	✅	llm	Collection
pipeline_json	string	✅	llm	Pipeline as JSON array, e.g. [{"$match": {...}}, {"$group": {...}}]
limit	number	❌	form	Safety cap — appended automatically if no $limit stage present (default 100)

Output (JSON): Each result document is yielded as its own JSON message — directly iterable.

---

Insert Document

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database
collection_name	string	✅	llm	Collection
document_json	string	✅	llm	Document as JSON object, e.g. {"name": "Alice", "age": 30}

Output: { "database", "collection", "inserted_id", "acknowledged": true }

---

Update Documents

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database
collection_name	string	✅	llm	Collection
filter_json	string	✅	llm	Filter JSON, e.g. {"status": "pending"}
update_json	string	✅	llm	Update JSON, e.g. {"$set": {"status": "done"}}
upsert	boolean	❌	form	Insert if no match (default false)

Output: { "database", "collection", "matched_count", "modified_count", "upserted_id", "acknowledged" }

---

Delete Documents

Parameter	Type	Required	Form	Description
database_name	string	✅	form	Database
collection_name	string	✅	llm	Collection
filter_json	string	✅	llm	Filter JSON, e.g. {"status": "archived"}

⚠️ Passing {} as filter_json deletes all documents in the collection.

Output: { "database", "collection", "deleted_count", "acknowledged" }

---

Recommended Workflow (with Voyage AI)

User query → Voyage AI Embed Text (input_type=query)
               ↓ output: text (JSON float array)
          → MongoDB Atlas Vector Search (query_vector = {{embed.text}})
               ↓ json output: json[0], json[1], ... (individual documents)
               ↓ text output: stringified doc array (for reranker)
          → Voyage AI Rerank (query, documents = {{vector_search.text}})
               ↓ json output: json[0], json[1], ... (ranked results)
          → Iterate node / LLM answer node

Note: All query/search tools yield one JSON message per document. This means json[0], json[1], etc. are individual documents — you can pipe the output directly to an Iterate or Loop node without extracting a nested field.

---

Observability

All MongoClient connections use appname="devrel-integration-atlas-dify-python", which appears in Atlas logs and the Atlas Monitoring dashboard under Application Names.

---

Support

• GitHub Issues: https://github.com/mongodb-developer/dify-plugins-mongodbatlas-tool/issues
• MongoDB Developer Community: https://www.mongodb.com/community/forums/

---

License

Apache 2.0 — see LICENSE for details.