MCP-Utils

MCP-Utils is a TypeScript utility library designed to support MCP server development with MongoDB connectivity, encryption utilities, Claude Desktop integration, and cross-platform configurations. It exposes a set of core utilities you can import and use in your MCP servers, including: MongoDB connection setup, AES-256-GCM token encryption/decryption, Claude config management for automatic server entries, port management to kill conflicting processes on launch, and structured logging and error handling. The library is designed to be used as a toolkit within MCP server projects and can be executed via npx using the GitHub master branch installation, enabling rapid experimentation and integration with Claude Desktop workflows. To get started, install the server via npx and supply required environment variables such as your MongoDB connection string and token secret. The package focuses on providing reliable primitives you can compose into a complete MCP server, rather than shipping a full standalone server binary.

Prerequisites:

• Node.js 18+ and npm
• GitHub access (to install from the GitHub repo)

Install with npm (via npx from GitHub):

1. Ensure you have a MongoDB instance and a secret for token encryption:

   • Create or note your MongoDB connection string (MONGODB_URI)
   • Create a 32-byte hex secret for tokens (TOKEN_SECRET)

2. Install and run the MCP-Utils package from GitHub:

# Option A: Run directly with npx (no local install required)
npx -y github:pdas9647/MCP-Utils#master

# Option B: Install locally for reuse (in your project)
npm install github:pdas9647/MCP-Utils#master

3. Verify environment variables are set (either in your shell or a .env) before running the server:

export MONGODB_URI="mongodb://localhost:27017/your-database"
export TOKEN_SECRET="0123456789abcdef0123456789abcdef"  # 32-byte hex

4. If you’re integrating into an MCP server workflow, ensure your run command references the proper entry points provided by MCP-Utils when composing your MCP server stack.

Tips and common considerations:

• Environment variables: MONGODB_URI and TOKEN_SECRET are commonly required by the utilities in MCP-Utils (for DB access and token encryption). Adjust based on your deployment needs.
• Claude Desktop integration: The library offers utilities to update Claude config across platforms. Use setEntry and addOrUpdateMCPServer to synchronize your server entries with Claude Desktop automatically.
• Port management: Use killPortOnLaunch to clear a port before starting a server to avoid conflicts. Combine with freezePortOnQuit to ensure clean shutdown behavior.
• Logging and errors: Leverage printInConsole for structured console logs and sendError for consistent error reporting with context information.
• Cross-platform considerations: The library includes utilities and examples that work across macOS, Windows, and Linux; ensure you test in your target environment.
• Security: Use AES-256-GCM encryption for tokens; manage your secret keys securely (do not hard-code in production).