mcpenv

Managing MCP servers like pyenv manages Python

CLI utility for managing Model Context Protocol server configurations across projects

TypeScriptNode.jscommander.jsAJVJest

View source →

A CLI utility for managing MCP (Model Context Protocol) server configurations, inspired by tools like pyenv and rbenv. Define, manage, and switch between different server environments and profiles on a per-project basis.

Problem

Working with multiple MCP servers across projects creates configuration conflicts. Each project might need different servers, different versions, or different settings. Without tooling, you’re manually editing JSON files and hoping nothing breaks.

Architecture

TypeScript-based Node.js application with layered architecture:

  • CLI Layer: commander.js for the interface
  • Services: Config management, backups, file locking
  • Models: Data structures and types
  • Validation: JSON Schema enforcement via AJV

Operates on local project files (.mcp.json, .mcpenv/) with these scopes:

Configuration Precedence (highest → lowest):
1. Local Overrides (.mcpenv/local.json) - User-specific
2. Lock File (mcpenv.lock) - Exact versions
3. Project Config (mcpenv.json) - Team-shared
4. Aggregated Registry (~/.mcpenv/registry.local.json)
5. Registry Source Priority - User-configured

Key Features

  • Profile System: Named configurations for different server setups
  • File Locking: Safe concurrent access to configs
  • Automatic Backups: Rotation-based backup system
  • Schema Validation: Rigorous JSON Schema enforcement
  • Multi-Source Registry: Official + community + private registries
  • Lock Files: Reproducible team installations

Current Status

Development Process

The project uses a Spec-Driven Development (SDD) workflow:

  1. /specify — Generate feature specs from requirements
  2. /plan — Implementation plans with technical artifacts
  3. /tasks — Granular, dependency-ordered developer tasks

Each feature lives in specs/NNN-feature-name/ with spec.md, plan.md, tasks.md, research notes, data models, and API contracts.

Why This Exists

MCP servers are becoming the standard way to extend AI assistants with tools and context. But managing them at scale—across teams, projects, and environments—requires the same rigor we apply to language versions and package dependencies. mcpenv brings that discipline to the MCP ecosystem.