> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB Vector Search Tool

> The `MongoDBVectorSearchTool` performs vector search on MongoDB Atlas with optional indexing helpers.

# `MongoDBVectorSearchTool`

## Description

The `MongoDBVectorSearchTool` enables vector similarity queries on MongoDB Atlas collections. MongoDB Atlas
supports native vector search. The tool also supports index creation helpers and bulk insert of embedded texts.

MongoDB Vector Search is useful for applications that want to use a vector search database to query data
with semantic search, filter queries on other fields in your collection, or power your
AI applications and agentic systems by implementing retrieval-augmented generation (RAG).

Learn more: [https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/)

## Installation

Install with the MongoDB extra:

```shell theme={null}
pip install crewai-tools[mongodb]
```

or

```shell theme={null}
uv add crewai-tools --extra mongodb
```

## Initialization Parameters

* `connection_string` (str): Required. MongoDB Atlas connection string credentials to connect to your cluster.
* `database_name` (str): Required. The name of the MongoDB database to use.
* `collection_name` (str): Required. The collection within the database where documents and embeddings are stored.
* `vector_index_name` (str, default: `vector_index`): Optional. The name of the MongoDB Vector Search index to query (must match the index
  created in Atlas).
* `text_key` (str, default: `text`): Optional. The document field name where raw text is stored.
* `embedding_key` (str, default: `embedding`): Optional. The document field name where the vector embedding is stored.
* `dimensions` (int, default: `1536`): Optional. The number of dimensions for the embedding model (must match your model).
* `query_config` (MongoDBVectorSearchConfig): Optional. A `MongoDBVectorSearchConfig` object for advanced query settings, like `limit` and `oversampling_factor`.

## MongoDBVectorSearchTool Methods

* `run(query=...)`: Embeds a query and performs vector similarity search, returning matching documents.
  Takes a natural language `query` (`str`) parameter to embed and search.
* `add_texts(list of strings)`: Takes a list of strings to embed and insert as documents into your MongoDB Atlas database.
* `create_vector_search_index(dimensions=...)`: Provisions a MongoDB Vector Search index with the correct dimensions
  and similarity. Takes a `dimensions` (int) parameter.

## Quick start

The following example demonstrates how to initialize the tool and execute a vector similarity search against the
specified MongoDB Atlas collection:

```python Code theme={null}
from crewai_tools import MongoDBVectorSearchTool

tool = MongoDBVectorSearchTool(
  connection_string="mongodb+srv://...",
  database_name="mydb",
  collection_name="docs",
)

print(tool.run(query="how to create vector index"))
```

## Common issues

* Authentication failures: ensure your Atlas IP Access List allows your runner and the connection string includes credentials.
* Index not found: create the vector index first; name must match `vector_index_name`.
* Dimensions mismatch: align embedding model dimensions with `dimensions`.

## Examples

### Preload the database and create the index

The following example demonstrates how to preload your MongoDB Atlas database with documents
and create a MongoDB Vector Search index to query your collection:

```python Code theme={null}
import os
from crewai_tools import MongoDBVectorSearchTool

tool = MongoDBVectorSearchTool(
    database_name="example_database",
    collection_name="example_collection",
    connection_string="<your_mongodb_connection_string>",
    dimensions=3072,
)

# Load text content from a local folder and add to your MongoDB collection
texts = []
for fname in os.listdir("knowledge"):
    path = os.path.join("knowledge", fname)
    if os.path.isfile(path):
        with open(path, "r", encoding="utf-8") as f:
            texts.append(f.read())

tool.add_texts(texts)

# Create the MongoDB Vector Search index (e.g., 3072 dims for text-embedding-3-large)
tool.create_vector_search_index(dimensions=3072)
```

### Custom query configuration and agent configuration

The following example demonstrates how to provide a custom query configuration to the `MongoDBVectorSearchTool`
and integrate with a CrewAI agent:

```python Code theme={null}
from crewai_tools import MongoDBVectorSearchConfig, MongoDBVectorSearchTool

query_config = MongoDBVectorSearchConfig(limit=10, oversampling_factor=2)
tool = MongoDBVectorSearchTool(
    database_name="example_database",
    collection_name="example_collection",
    connection_string="<your_mongodb_connection_string>",
    query_config=query_config,
    vector_index_name="my_vector_index",
)

rag_agent = Agent(
    name="rag_agent",
    role="You are a helpful assistant that can answer questions with the help of the MongoDBVectorSearchTool.",
    goal="...",
    backstory="...",
    tools=[tool],
)
```

### Run a CrewAI workflow

The following example demonstrates how to integrate your `MongoDBVectorSearchTool` with an Agent, Task, and
Crew to create and run a CrewAI agentic RAG workflow:

```python Code theme={null}
from crewai import Agent, Task, Crew
from crewai_tools import MongoDBVectorSearchTool

tool = MongoDBVectorSearchTool(
    connection_string="mongodb+srv://...",
    database_name="mydb",
    collection_name="docs",
)

agent = Agent(
    role="RAG Agent",
    goal="Answer using MongoDB vector search",
    backstory="Knowledge retrieval specialist",
    tools=[tool],
    verbose=True,
)

task = Task(
    description="Find relevant content for 'indexing guidance'",
    expected_output="A concise answer citing the most relevant matches",
    agent=agent,
)

crew = Crew(
    agents=[agent], 
    tasks=[task],
    verbose=True,
)

result = crew.kickoff()
```

## Learn More

To learn more about CrewAI integrations with MongoDB, see the following MongoDB guides:

* [Integrate MongoDB with CrewAI](https://www.mongodb.com/docs/atlas/ai-integrations/crewai/)
* [Build an Agentic RAG Application with CrewAI and MongoDB](https://www.mongodb.com/docs/atlas/ai-integrations/crewai/build-agents/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.