embabel-mongo

This MCP server acts as a bridge between AI agents and a MongoDB database using the Embabel framework and Spring Boot. It exposes a set of tools (via the MCP protocol) that let an AI agent list databases and collections, run simple and complex JSON queries, manage indexes, and insert documents, all through natural language prompts. Tools are auto-exposed from Java services using Embabel's Export annotation, so you can invoke operations like listing databases, querying collections, and inserting documents directly from your agent UI or MCP Inspector.

To use it, first ensure the server is running and accessible at the MCP endpoint /sse. The server supports commands such as listing databases, listing collections within a database, executing JSON-based queries, and inserting documents. In tooling configurations (e.g., Claude Desktop or MCP Inspector), you’ll point the MCP client to the SSE URL and use descriptive prompts like “List all databases” or “Insert a document into test_db.users.” The server translates these prompts into MongoDB operations and returns results back to the agent. You can inspect and test the exposed tools via the MCP Inspector UI by connecting to http://localhost:8080/sse once the app is running.

Prerequisites:

• Java 21 or higher
• Maven
• MongoDB running locally (port 27017) or accessible remotely
• OpenRouter API key for embedding capabilities

Step-by-step:

1. Clone the repository

git clone https://github.com/BootcampToProd/embabel-mongo-mcp-server.git
cd embabel-mongo-mcp-server

2. Ensure prerequisites are installed (Java and Maven)

java -version
mvn -version

3. Configure environment variables (example values):

export OPENAI_API_KEY={YOUR_OPENROUTER_API_KEY}
export MONGO_HOST=localhost
export MONGO_PORT=27017

4. Build and run the application

mvn clean install
mvn spring-boot:run

The server will start and expose the MCP endpoint at http://localhost:8080/sse.

Notes and tips:

• The MCP endpoint is exposed at /sse when the Spring Boot application is running. Ensure port 8080 is open if you are behind a firewall.
• Set MONGO_HOST and MONGO_PORT to point to your MongoDB instance. You can also provide authentication details if using a secured MongoDB deployment.
• The Embabel framework uses the @Export annotation for tool exposure. If you modify services, recompile to reflect changes in MCP tooling.
• If you plan to test with Claude Desktop, ensure the Claude config points to the embedded MCP server via the SSE URL and uses the npx-based invocation shown in the README example.
• For troubleshooting, check application logs for MongoDB connection issues or OpenRouter API errors; common issues include incorrect API keys or inaccessible MongoDB endpoints.