mcp-mongo-server - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #llm #go #android #machine-learning #deep-learning #macos #cli #vue #awesome-list #openai

mcp-mongo-server

(★ 284)

A Model Context Protocol Server for MongoDB

파일 탐색기

최종 버전 다운로드 (.zip)

- - publish-github-packages.yml
  - publish-npm-packages.yml
- development.md
- integration.md
- tools.md
- claude-desktop-env.jsonc
- claude-desktop.jsonc
- cursor.jsonc
- docker-compose.yml
- github-package.jsonc
- inspector-config.jsonc
- windsurf.jsonc
- - call.ts
  - completion.ts
  - ping.ts
  - prompts.ts
  - resource.ts
  - templates.ts
  - tools.ts
- - pagination.ts
- index.ts
- mongo.ts
- server.ts
.dockerignore
.gitignore
.npmrc-github
biome.json
bun.lock
CONTRIBUTING.md
docker-compose.yml
Dockerfile
LICENSE
package.json
README.md
smithery.yaml
tsconfig.json
tsup.config.ts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/kiliczsh/mcp-mongo-server

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd mcp-mongo-server

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker compose up -d --build

정의된 모든 컨테이너(서버, DB 등)를 한 번에 빌드하고 백그라운드에서 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

3. Node.js

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm start

개발/실행 서버를 켭니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MCP MongoDB Server
---

![NPM Version](https://img.shields.io/npm/v/mcp-mongo-server)
![NPM Downloads](https://img.shields.io/npm/dm/mcp-mongo-server)
![NPM License](https://img.shields.io/npm/l/mcp-mongo-server)

A Model Context Protocol (MCP) server that lets AI assistants work with your MongoDB databases. It exposes your collections, infers their schemas, and runs queries, aggregations, and writes through a standard interface — so tools like Claude Desktop and Cursor can read and reason about your data.

## Demo

[![MCP MongoDB Server Demo | Claude Desktop](https://img.youtube.com/vi/FI-oE_voCpA/0.jpg)](https://www.youtube.com/watch?v=FI-oE_voCpA)

## Why use it

- **Talk to your database in plain language** — the assistant discovers your collections and their shape automatically.
- **Safe by default** — turn on read-only mode to let an assistant explore without any risk of changing data.
- **Works everywhere** — connects to standalone, replica set, sharded, and Atlas deployments, over plain or TLS connections.

## Key Features

- **Read-Only Mode** — blocks every write path (insert, update, index creation, and aggregation stages like `$out`/`$merge` that could modify data).
- **Smart ObjectId Handling** — configurable `auto`/`none`/`force` conversion of 24-character hex strings to ObjectIds.
- **Schema Inference** — automatic collection schema detection from document samples.
- **Query & Aggregation** — full query and aggregation pipeline support, with optional `explain` plans.
- **Write Operations** — insert, update, and index creation (when read-only mode is off).
- **Time Conversion** — a `convertTime` helper turns Unix timestamps and date strings into UTC/GMT/ISO, so date queries stay unambiguous across timezones.
- **Progress & Cancellation** — long operations report progress and can be cancelled mid-flight.
- **Two Transports** — run locally over stdio, or expose an HTTP endpoint for remote access.

## Requirements

- Node.js 20 or newer

## Quick Start

Point the server at your database — no install step needed:

```bash
npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase
```

Explore safely, without any chance of changing data:

```bash
npx -y mcp-mongo-server mongodb://localhost:27017/mydatabase --read-only
```

## Usage

### Local (stdio)

This is the default, used by Claude Desktop, Cursor, and other local clients:

```bash
npx -y mcp-mongo-server "mongodb://user:pass@localhost:27017/mydatabase"
```

### Remote (HTTP)

Expose an HTTP endpoint at `/mcp` for remote or multi-client access:

```bash
npx -y mcp-mongo-server "mongodb://user:pass@localhost:27017/mydatabase" --transport http --port 3001
```

By default, only requests without a browser `Origin` (CLIs, IDEs) and requests
from `localhost` are accepted; everything else is rejected with `403` to guard
against DNS-rebinding attacks. Allow specific browser origins with
`--allowed-origins`:

```bash
npx -y mcp-mongo-server "mongodb://..." --transport http --port 3001 --allowed-origins "https://app.example.com"
```

### Options

| Flag | Description |
|------|-------------|
| `--read-only`, `-r` | Block all write operations |
| `--allow-cross-db` | Allow aggregation `$out`/`$merge`/`$lookup` to target other databases (off by default) |
| `--allow-server-js` | Allow server-side JavaScript operators `$function`/`$where`/`$accumulator` (off by default) |
| `--transport`, `-t` | `stdio` (default) or `http` |
| `--port`, `-p` | HTTP port (default `3001`) |
| `--allowed-origins` | Comma-separated browser origins to allow in HTTP mode |
| `--json-limit` | Max HTTP request body size (default `10mb`) |
| `--auth-token` | Require `Authorization: Bearer <token>` on the HTTP endpoint |

### Environment Variables

| Variable | Description |
|----------|-------------|
| `MCP_MONGODB_URI` | MongoDB connection URI (alternative to the argument) |
| `MCP_MONGODB_READONLY` | Enable read-only mode (`"true"`) |
| `MCP_MONGODB_ALLOW_CROSS_DB` | Allow cross-database aggregation stages (`"true"`) |
| `MCP_MONGODB_ALLOW_SERVER_JS` | Allow server-side JavaScript operators (`"true"`) |
| `MCP_PORT` | HTTP port |
| `MCP_HTTP_ALLOWED_ORIGINS` | Comma-separated browser origins to allow in HTTP mode |
| `MCP_HTTP_JSON_LIMIT` | Max HTTP request body size (default `10mb`) |
| `MCP_HTTP_AUTH_TOKEN` | Bearer token required to access the HTTP endpoint |

## Security

**Database scope.** The server operates on the database in your connection
string. Aggregation stages that reach another database (`$out`, `$merge`,
`$lookup` with an explicit `db`) are rejected by default, so a pipeline can't
quietly read from or write to databases you didn't point it at. Enable them
with `--allow-cross-db` if you need them.

**Server-side JavaScript.** The aggregation operators `$function`, `$where`,
and `$accumulator` run arbitrary JavaScript on the MongoDB server. They are
rejected by default; enable them with `--allow-server-js` if you trust the
pipelines being run.

**Read-only mode** blocks every write path, including aggregation stages that
write or run server-side JavaScript (`$out`, `$merge`, `$function`, `$where`,
`$accumulator`).

**Least privilege.** Application-level checks only go so far — the strongest
guarantee comes from the database. Connect with a MongoDB user scoped to just
the database you need, with read-only permissions when the assistant only needs
to explore. That way the database itself enforces the boundary, as defense in
depth.

## Documentation

- [Integration Guide](docs/integration.md) — Claude Desktop, Windsurf, Cursor, Docker
- [Available Tools](docs/tools.md) — query, aggregate, update, insert, and more
- [Development](docs/development.md) — setup, scripts, and debugging
- [Contributing](CONTRIBUTING.md)

## License

MIT — see [LICENSE](LICENSE) for details.