mongo_agent_mcp 0.1.0__py3-none-any.whl

mongo_agent_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,404 @@
+Metadata-Version: 2.4
+Name: mongo_agent_mcp
+Version: 0.1.0
+Summary: A mongo mcp that can be used to automate the database query with llm 
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: pymongo>=4.17.0
+
+# MongoDB MCP
+
+A MongoDB Model Context Protocol (MCP) Server that allows AI agents and MCP clients to interact with MongoDB databases through standardized tools.
+
+## Features
+
+* List all collections
+* Discover collection schemas
+* Fetch collection data
+* Query documents
+* Insert documents
+* Update documents
+* Delete documents
+* MongoDB Atlas support
+* Local MongoDB support
+* MCP stdio transport support
+
+---
+
+# Installation
+
+## Using pip
+
+```bash
+pip install mongo-mcp
+```
+
+## Using uv
+
+```bash
+uv add mongo-mcp
+```
+
+---
+
+# Prerequisites
+
+* Python 3.10+
+* MongoDB Local Instance or MongoDB Atlas Cluster
+
+Examples:
+
+```txt
+mongodb://localhost:27017
+```
+
+or
+
+```txt
+mongodb+srv://username:password@cluster.mongodb.net
+```
+
+---
+
+# Configuration
+
+MongoDB MCP uses environment variables to connect to your database.
+
+Create a `.env` file:
+
+```env
+MONGODB_URI=mongodb://localhost:27017
+DATABASE_NAME=shipbihar
+```
+
+## Environment Variables
+
+| Variable      | Description               | Required |
+| ------------- | ------------------------- | -------- |
+| MONGODB_URI   | MongoDB connection string | Yes      |
+| DATABASE_NAME | Database name             | Yes      |
+
+---
+
+# Running the MCP Server
+
+```bash
+mongo_mcp
+```
+
+or
+
+```bash
+python -m mongo_mcp.main
+```
+
+The MCP server will start using stdio transport.
+
+---
+
+# MCP Client Configuration
+
+Example MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "mongodb": {
+      "command": "mongo_mcp",
+      "env": {
+        "MONGODB_URI": "mongodb://localhost:27017",
+        "DATABASE_NAME": "shipbihar"
+      }
+    }
+  }
+}
+```
+
+---
+
+# Available Tools
+
+## all_collections
+
+Returns all collections in the configured database.
+
+Example Output:
+
+```json
+[
+  "users",
+  "orders",
+  "shipments"
+]
+```
+
+---
+
+## fetch_collection_schema
+
+Returns an inferred schema from a sample document.
+
+Example:
+
+```json
+{
+  "_id": "ObjectId",
+  "name": "str",
+  "email": "str",
+  "createdAt": "datetime"
+}
+```
+
+---
+
+## fetch_collection_data
+
+Returns documents from a collection.
+
+Parameters:
+
+```json
+{
+  "collection_name": "users",
+  "limit": 100
+}
+```
+
+---
+
+## find_document
+
+Find a document using a MongoDB query.
+
+Example:
+
+```json
+{
+  "collection_name": "users",
+  "query": {
+    "email": "john@example.com"
+  }
+}
+```
+
+---
+
+## insert_document
+
+Insert a document.
+
+Example:
+
+```json
+{
+  "collection_name": "users",
+  "document": {
+    "name": "John",
+    "email": "john@example.com"
+  }
+}
+```
+
+---
+
+## update_document
+
+Update matching documents.
+
+Example:
+
+```json
+{
+  "collection_name": "users",
+  "filter_query": {
+    "email": "john@example.com"
+  },
+  "update_data": {
+    "role": "admin"
+  }
+}
+```
+
+---
+
+## delete_document
+
+Delete matching documents.
+
+Example:
+
+```json
+{
+  "collection_name": "users",
+  "filter_query": {
+    "email": "john@example.com"
+  }
+}
+```
+
+---
+
+# Common Errors
+
+## Error: DATABASE_NAME is None
+
+Error:
+
+```txt
+TypeError: name must be an instance of str, not <class 'NoneType'>
+```
+
+Reason:
+
+MongoDB MCP cannot find the `DATABASE_NAME` environment variable.
+
+Solution:
+
+Create a `.env` file:
+
+```env
+MONGODB_URI=mongodb://localhost:27017
+DATABASE_NAME=your_database_name
+```
+
+or export variables manually.
+
+Windows PowerShell:
+
+```powershell
+$env:MONGODB_URI="mongodb://localhost:27017"
+$env:DATABASE_NAME="shipbihar"
+```
+
+Linux/macOS:
+
+```bash
+export MONGODB_URI="mongodb://localhost:27017"
+export DATABASE_NAME="shipbihar"
+```
+
+---
+
+## Error: Connection Refused
+
+Error:
+
+```txt
+ServerSelectionTimeoutError
+```
+
+Reason:
+
+MongoDB server is not running.
+
+Solution:
+
+Start MongoDB:
+
+```bash
+mongod
+```
+
+or verify your Atlas connection string.
+
+---
+
+## Error: Authentication Failed
+
+Error:
+
+```txt
+Authentication failed
+```
+
+Reason:
+
+Incorrect username or password.
+
+Solution:
+
+Verify your MongoDB credentials.
+
+---
+
+# Security
+
+Recommended:
+
+* Use dedicated database users
+* Restrict permissions when possible
+* Avoid connecting with admin credentials
+* Store secrets in environment variables
+
+Do NOT:
+
+* Commit `.env` files to GitHub
+* Hardcode MongoDB passwords in code
+
+---
+
+# Development
+
+Clone the repository:
+
+```bash
+git clone <repository-url>
+cd mongo-mcp
+```
+
+Create environment:
+
+```bash
+uv venv
+source .venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Run locally:
+
+```bash
+python -m mongo_mcp.main
+```
+
+---
+
+# Roadmap
+
+## V1
+
+* Collection discovery
+* CRUD operations
+* Schema inspection
+
+## V2
+
+* Aggregation pipelines
+* Count documents
+* Regex search
+
+## V3
+
+* Natural language queries
+* Query optimization
+* Schema caching
+
+---
+
+# License
+
+MIT License
+
+---
+
+# Author
+
+Vishnu Bhardwaj
+
+Built for AI Agents, MCP Clients, and MongoDB Developers.

mongo_agent_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mongo_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mongo_mcp/main.py,sha256=xE1M3lcMLDz-_Kpk-DAtl8S-Yl1F7ULT5n_zVJ3I-ck,124
+mongo_mcp/tools.py,sha256=ooSzk4I46k6HK8CEl_HmelQTDEJwvTqudYmJO6BeBV0,3832
+mongo_agent_mcp-0.1.0.dist-info/METADATA,sha256=eC7p1BoAH-Xefnxj_fCKIQ1VtMBHW_aTIkCs5FnWEhY,5333
+mongo_agent_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mongo_agent_mcp-0.1.0.dist-info/entry_points.txt,sha256=GJ0esSmtZWEkIX6HNHASREt9injyYauZsUyeRLzsfK0,50
+mongo_agent_mcp-0.1.0.dist-info/top_level.txt,sha256=nU4IZ7nMfeJXnfIN3mbwrmwHWzdXqVezA3UYQBjIF1A,10
+mongo_agent_mcp-0.1.0.dist-info/RECORD,,

mongo_agent_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mongo_agent_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mongo_mcp = mongo_mcp.main:main

mongo_agent_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mongo_mcp

mongo_mcp/main.py

@@ -0,0 +1,11 @@
+from mongo_mcp.tools import mcp
+
+def main():
+  mcp.run(transport="stdio")
+
+
+
+
+
+if __name__ == "__main__":
+  main()

mongo_mcp/tools.py

@@ -0,0 +1,203 @@
+
+from fastmcp import FastMCP
+from pymongo import MongoClient
+from dotenv import load_dotenv
+import os
+
+# Load environment variables
+load_dotenv()
+
+# MongoDB Connection
+client = MongoClient(os.getenv("MONGODB_URI"))
+db = client[os.getenv("DATABASE_NAME")]
+
+# MCP Instance
+mcp = FastMCP("MongoDB MCP")
+
+
+# =========================
+# COLLECTION TOOLS
+# =========================
+
+@mcp.tool()
+def all_collections():
+    """
+    Returns all collections in the database.
+    """
+    try:
+        return db.list_collection_names()
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def fetch_collection_schema(collection_name: str):
+    """
+    Returns inferred schema from a sample document.
+    """
+
+    try:
+        doc = db[collection_name].find_one()
+
+        if not doc:
+            return {"error": "Collection is empty"}
+
+        return {
+            key: type(value).__name__
+            for key, value in doc.items()
+        }
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# =========================
+# READ TOOLS
+# =========================
+
+@mcp.tool()
+def fetch_collection_data(
+    collection_name: str,
+    limit: int = 100
+):
+    """
+    Fetch documents from a collection.
+    """
+
+    try:
+        documents = list(
+            db[collection_name]
+            .find()
+            .limit(limit)
+        )
+
+        for doc in documents:
+            doc["_id"] = str(doc["_id"])
+
+        return documents
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def find_document(
+    collection_name: str,
+    query: dict
+):
+    """
+    Find a single document.
+    """
+
+    try:
+        document = db[collection_name].find_one(query)
+
+        if not document:
+            return {"message": "Document not found"}
+
+        document["_id"] = str(document["_id"])
+
+        return document
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def count_documents(
+    collection_name: str,
+    query: dict = {}
+):
+    """
+    Count matching documents.
+    """
+
+    try:
+        count = db[collection_name].count_documents(query)
+
+        return {"count": count}
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# =========================
+# INSERT TOOL
+# =========================
+
+@mcp.tool()
+def insert_document(
+    collection_name: str,
+    document: dict
+):
+    """
+    Insert a document.
+    """
+
+    try:
+        result = db[collection_name].insert_one(document)
+
+        return {
+            "success": True,
+            "inserted_id": str(result.inserted_id)
+        }
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# =========================
+# UPDATE TOOL
+# =========================
+
+@mcp.tool()
+def update_document(
+    collection_name: str,
+    filter_query: dict,
+    update_data: dict
+):
+    """
+    Update matching document.
+    """
+
+    try:
+        result = db[collection_name].update_one(
+            filter_query,
+            {"$set": update_data}
+        )
+
+        return {
+            "matched_count": result.matched_count,
+            "modified_count": result.modified_count
+        }
+
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# =========================
+# DELETE TOOL
+# =========================
+
+@mcp.tool()
+def delete_document(
+    collection_name: str,
+    filter_query: dict
+):
+    """
+    Delete matching document.
+    """
+
+    try:
+        result = db[collection_name].delete_one(
+            filter_query
+        )
+
+        return {
+            "deleted_count": result.deleted_count
+        }
+
+    except Exception as e:
+        return {"error": str(e)}
+