Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mastra-ai/mastra/llms.txt

Use this file to discover all available pages before exploring further.

MongoDB storage provides flexible schema-less document storage for Mastra with native support for nested data structures.

​
Installation

npm install @mastra/mongodb

​
Configuration

1

Import MongoDBStore

import { MongoDBStore } from '@mastra/mongodb';
2

Create storage instance

const storage = new MongoDBStore({
  id: 'my-storage',
  uri: process.env.MONGODB_URI!,
});
3

Configure Mastra

import { Mastra } from '@mastra/core';

const mastra = new Mastra({
  storage,
});

​
Configuration Options

​
id
string
required
Unique identifier for the storage instance
​
uri
string
required
MongoDB connection URI (e.g., mongodb://localhost:27017 or mongodb+srv://...)
​
databaseName
string
default:"mastra"
Name of the MongoDB database to use
​
disableInit
boolean
default:false
Disable automatic collection and index creation

​
Usage Examples

​
Basic Configuration

import { MongoDBStore } from '@mastra/mongodb';
import { Mastra } from '@mastra/core';

const storage = new MongoDBStore({
  id: 'storage',
  uri: process.env.MONGODB_URI!,
  databaseName: 'mastra_prod',
});

const mastra = new Mastra({
  storage,
});

​
Access Storage Domains

const storage = new MongoDBStore({
  id: 'storage',
  uri: process.env.MONGODB_URI!,
});

// Access memory domain
const memory = await storage.getStore('memory');
await memory?.saveThread({ thread });

// Access workflows domain
const workflows = await storage.getStore('workflows');
await workflows?.persistWorkflowSnapshot({
  workflowName: 'my-workflow',
  runId: 'run-123',
  snapshot,
});

​
MongoDB Atlas

const storage = new MongoDBStore({
  id: 'atlas-storage',
  uri: `mongodb+srv://${process.env.ATLAS_USER}:${process.env.ATLAS_PASSWORD}@${process.env.ATLAS_CLUSTER}.mongodb.net/?retryWrites=true&w=majority`,
  databaseName: 'mastra',
});

​
Local Development

const storage = new MongoDBStore({
  id: 'dev-storage',
  uri: 'mongodb://localhost:27017',
  databaseName: 'mastra_dev',
});

​
Storage Domains

MongoDB storage supports all Mastra domains:
  • memory - Thread-based conversation persistence
  • workflows - Workflow execution snapshots
  • observability - Telemetry and logging
  • agents - Agent configurations
  • mcpClients - MCP client configurations
  • mcpServers - MCP server configurations
  • blobs - Binary large object storage

​
Vector Store Support

MongoDB also provides vector search capabilities: 
import { MongoDBVector } from '@mastra/mongodb';

const vectorStore = new MongoDBVector({
  id: 'vectors',
  uri: process.env.MONGODB_URI!,
  databaseName: 'mastra',
});

const mastra = new Mastra({
  vectors: {
    embeddings: vectorStore,
  },
});

​
Best Practices

Connection String Security

Store MongoDB credentials in environment variables:
uri: process.env.MONGODB_URI!

Database Naming

Use descriptive database names per environment:
databaseName: `mastra_${process.env.NODE_ENV}`

Atlas Deployment

Use MongoDB Atlas for production deployments with automatic backups and scaling.

Indexes

MongoDB automatically creates indexes for common query patterns.

​
Performance Considerations

​
Connection Pooling

MongoDB driver automatically manages connection pooling. For high-traffic applications: 
const storage = new MongoDBStore({
  id: 'storage',
  uri: `${process.env.MONGODB_URI}?maxPoolSize=50&minPoolSize=10`,
  databaseName: 'mastra',
});

​
Write Concerns

Adjust write concerns in connection string for durability vs performance: 
// High durability (default)
uri: `${process.env.MONGODB_URI}?w=majority`

// Higher performance (less durable)
uri: `${process.env.MONGODB_URI}?w=1`

MongoDB Vector

MongoDB Atlas Vector Search

PostgreSQL Storage

Alternative SQL storage option

MongoDB Docs

Official MongoDB documentation

MongoDB Atlas

Fully managed MongoDB service

Build docs developers (and LLMs) love

Get started for freeTalk to us