Registry / aws / mongodb-atlas-api-client

mongodb-atlas-api-client

JSON →
library4.14.0jsnpmunverified

This Node.js client provides programmatic access to the MongoDB Atlas Administration API, enabling management of Atlas resources such as clusters, users, and projects. It abstracts the complexities of HTTP Digest Authentication by internally using the `urllib` package. The current stable version is 4.14.0. Releases are typically driven by updates to Node.js versions or resolutions of dependency vulnerabilities, rather than a fixed cadence. A key differentiator is its direct focus on managing Atlas via API keys, providing a more granular control for automation compared to the broader MongoDB Node.js driver. It ships with comprehensive TypeScript types, facilitating type-safe development. Additionally, it offers explicit support for integration with Model Context Protocol (MCP) servers, enabling AI assistants to interact with Atlas resources through natural language. This library is specifically designed for server-side Node.js environments.

npm install mongodb-atlas-api-client
INSTALL
IMPORT
SIG · MONGODB-ATLAS-API-
M
mongodb-atlas-api-client
awsjavascriptv4.14.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

getClient
const getClient = require('mongodb-atlas-api-client');
const { getClient } = require('mongodb-atlas-api-client');
The `getClient` function is the default export in CommonJS, which then returns an object containing various API entities (e.g., `user`, `cluster`).
getClient
import getClient from 'mongodb-atlas-api-client';
import { getClient } from 'mongodb-atlas-api-client';
For ESM, `getClient` is the default export. This module supports Node.js >=18, making ESM imports viable.
AtlasClientOptions, UserApiClient
import type { AtlasClientOptions, UserApiClient } from 'mongodb-atlas-api-client';
The package ships with TypeScript types. `AtlasClientOptions` is a common pattern for client configuration, and `UserApiClient` for the returned API entities, though specific type names might vary, they are provided for type-safe usage.

This quickstart initializes the MongoDB Atlas API client and demonstrates fetching all database users from a specified project using API keys. It includes environment variable usage and basic error handling for common API issues.

import getClient from 'mongodb-atlas-api-client'; const PUBLIC_KEY = process.env.ATLAS_PUBLIC_KEY ?? 'your-public-key'; const PRIVATE_KEY = process.env.ATLAS_PRIVATE_KEY ?? 'your-private-key'; const PROJECT_ID = process.env.ATLAS_PROJECT_ID ?? 'your-project-id'; if (!PUBLIC_KEY || !PRIVATE_KEY || !PROJECT_ID) { console.error('Missing MongoDB Atlas API keys or Project ID. Please set ATLAS_PUBLIC_KEY, ATLAS_PRIVATE_KEY, and ATLAS_PROJECT_ID environment variables or provide them directly.'); process.exit(1); } async function runAtlasClient() { try { const { user, cluster } = getClient({ publicKey: PUBLIC_KEY, privateKey: PRIVATE_KEY, baseUrl: "https://cloud.mongodb.com/api/atlas/v1.0", projectId: PROJECT_ID }); const options = { envelope: true, itemsPerPage: 5, pretty: true, httpOptions: { timeout: 10000 // 10 second timeout for urllib } }; console.log('Fetching all users...'); const allUsers = await user.getAll(options); console.log('Found users:', allUsers.results.map(u => u.username)); // Example: Fetch a specific cluster (replace 'yourClusterName' with an actual cluster name) // console.log('Fetching cluster: yourClusterName'); // const singleCluster = await cluster.get('yourClusterName'); // console.log('Cluster details:', singleCluster.name); } catch (error) { console.error('Error interacting with MongoDB Atlas API:', error); if (error.status === 401 || error.status === 403) { console.error('Authentication or Authorization error. Check your API keys and IP Access List.'); } } } runAtlasClient();
Debug
Known issues
breakingVersion 4.0.0 of `mongodb-atlas-api-client` dropped support for Node.js versions older than 18. Applications running on Node.js <18 will fail to initialize or execute.
fix
Upgrade your Node.js environment to version 18 or higher. Consider using an LTS version for production stability.
affects: >=4.0.0
breakingVersion 3.0.0 replaced `node-fetch` and `digest-fetch` with `urllib` due to reported vulnerabilities and incompatibility issues with newer versions of the original dependencies. While the library maintainer stated 'ideally there shouldn't be any breaking change,' changes to the underlying HTTP client might introduce subtle behavioral differences or unexpected issues in edge cases, particularly concerning HTTP options or error handling.
fix
Thoroughly test your application after upgrading to v3.0.0 or later to ensure continued compatibility, especially if you rely on specific HTTP client behaviors or custom `httpOptions`.
affects: >=3.0.0
breakingVersion 2.0.0 removed support for Node.js version 8. Running the client on Node.js 8 will result in compatibility errors.
fix
Ensure your Node.js environment is updated to a supported version. Node.js 18 or higher is recommended for current versions of the client.
affects: >=2.0.0
gotchaMongoDB Atlas API keys are considered a 'legacy authentication method' by MongoDB, with 'Service Accounts via OAuth 2.0' being the recommended approach for programmatic access. While this client still uses API keys, users should be aware of MongoDB's recommendation.
fix
For new projects or enhanced security, consider using MongoDB Atlas Service Accounts and OAuth 2.0 for authentication, potentially with a different client library or a custom implementation for token management. Otherwise, ensure API keys follow best practices for rotation and IP access lists.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: getClient is not a function
Incorrect CommonJS import for the `getClient` function.
fix
Use `const getClient = require('mongodb-atlas-api-client');` instead of `const { getClient } = require('mongodb-atlas-api-client');` as `getClient` is the default export.
Error interacting with MongoDB Atlas API: Error: status: 401, message: Unauthorized
Invalid MongoDB Atlas Public or Private API Key, or incorrect Project ID.
fix
Verify your `publicKey`, `privateKey`, and `projectId` in the `getClient` configuration. Ensure they are correct and have the necessary permissions within MongoDB Atlas.
Error interacting with MongoDB Atlas API: Error: status: 403, message: IP address <your-ip> is not allowed to access this resource
Your server's public IP address is not whitelisted in the MongoDB Atlas IP Access List for the project associated with your API keys.
fix
Add the public IP address of your application server to the IP Access List in your MongoDB Atlas project settings. For development, `0.0.0.0/0` can be used, but this is not recommended for production.
Upgrade
Version history
4.14.0latest on npm
Audit
Dependencies
urllibrequiredHandles underlying HTTP requests and digest authentication, replacing `node-fetch` and `digest-fetch` due to security vulnerabilities.
Agent activity
17 hits · last 30 days
node
16
OpenAI (training)
1
Resources