mcpd - MCP Server Lifecycle Manager

Intelligent daemon for managing MCP (Model Context Protocol) server processes

Think of it as "systemd for MCP servers, but smarter"

What is mcpd?

mcpd is a daemon and CLI tool that manages MCP server processes with:

• ✅ Intelligent idle detection - Auto-stop servers after inactivity
• ✅ Auto-start on demand - Servers restart when you need them
• ✅ Tool namespacing - Use tools from multiple servers without conflicts
• ✅ Hot reload - Update config without restarting
• ✅ Crash recovery - Automatic restart with exponential backoff
• ✅ Cross-platform - Works on Windows, Linux, and macOS

Installation

npm install -g @juncai/mcpd

Requirements

• Platform: Windows x64 (Linux and macOS support coming soon)
• Node.js: Version 12.0.0 or higher

Quick Start

1. Create Configuration

Create mcpserver.json in your project directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org"
      }
    }
  }
}

2. Start a Server

mcpd up filesystem

3. Check Status

mcpd ps

Output:

NAME          STATE     TOOL_COUNT
filesystem    running   14

4. List Tools

mcpd tools

5. Execute a Tool

mcpd exec filesystem.read_file '{"path": "/tmp/test.txt"}'

6. Stop Server

mcpd down filesystem

CLI Commands

# Server Management
mcpd up [servers...]           # Start servers (all if none specified)
mcpd down [--all]              # Stop servers
mcpd ps [-v] [server]          # Show status (verbose: -v or -vv)

# Tool Operations
mcpd tools [server]            # List available tools
mcpd tools [server] -v         # List tools with parameter details
mcpd tools [server] --json     # Output tools in JSON format
mcpd exec <tool> [args]        # Execute a tool

# Cache Management
mcpd load [servers...]         # Preload server metadata into cache
mcpd refresh [servers...]      # Refresh cached metadata

# Configuration
mcpd validate                  # Validate mcpserver.json
mcpd reload                    # Reload configuration
mcpd logs [server] [-f]        # View logs

# Daemon
mcpd daemon                    # Start daemon (internal)

Example Configuration

Example configurations are included in the package:

# View example daemon configuration
cat $(npm root -g)/mcpd/examples/mcpd.yml

# View example MCP server configuration
cat $(npm root -g)/mcpd/examples/mcpserver.json

Features

Metadata Caching (v1.1+)

mcpd caches tool definitions for instant startup:

• 30-600x faster startup (<100ms vs 3-60s)
• Query stopped servers - tools available from cache
• Persistent - survives daemon restarts
• Smart invalidation - auto-updates when config changes

HTTP Server Support (v1.2+)

Connect to HTTP-based MCP servers:

{
  "mcpServers": {
    "deepwiki": {
      "type": "http",
      "url": "https://mcp.deepwiki.com/mcp"
    },
    "custom-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Platform Support

| Platform | Architecture | Status | |----------|-------------|--------| | Windows | x64 | ✅ Supported | | Linux | x64 | 📋 Coming soon | | macOS | x64 | 📋 Coming soon | | macOS | ARM64 | 📋 Coming soon |

Troubleshooting

Unsupported Platform Error

If you see:

Error: Unsupported platform: linux-x64

This means the platform is not yet supported. Check for updates:

npm update -g mcpd

Server Won't Start

Check logs:

mcpd logs <server-name>

Common issues:

• Command not found: Install the MCP server package
• Permission denied: Check file permissions
• Port conflicts: Some servers need specific ports

Documentation

Full documentation: GitHub Repository

License

MIT License - see LICENSE file for details.

Links

• GitHub Repository
• Issue Tracker
• npm Package