Maestro MCP Manager

Easy setup and management for local MCP (Model Context Protocol) servers.

Installation

Install from npm

npm install -g @realeng/maestro

macOS Users - Download & Click Installation

1. Download the latest maestro-macos-vX.X.X.zip from Releases
2. Unzip the file
3. Double-click 1-install-maestro.command to install Maestro
4. Double-click 2-configure-servers.command to set up your MCP servers

macOS Users - From Source

1. Clone this repository
2. Double-click 1-install-maestro.command to install Maestro
3. Double-click 2-configure-servers.command to set up your MCP servers

Manual Installation from Source

1. Clone this repository
2. Install globally:

   npm install -g .

Or install for development:

1. Clone this repository
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Make the CLI globally available:

   npm link

Usage

Initialize MCP Servers

Configure authentication for MCP servers:

maestro init

This interactive command will:

• List available MCP servers
• Guide you through authentication setup (URLs, API tokens, etc.)
• Save credentials securely in ~/.maestro/config.json

Run MCP Servers

Start all configured MCP servers:

maestro run

This will:

• Start all enabled MCP servers
• Display port information for each server
• Keep servers running until you press Ctrl+C
• Save logs to ~/.maestro/logs/

Generate Claude Configuration

Generate configuration for Claude Desktop or Claude Code:

maestro mcp-config

This will:

• Create a JSON configuration for all your MCP servers
• Display the configuration in the terminal
• Save it to claude-config.json in the current directory
• Provide instructions for adding it to Claude

Sync to opencode

Sync your enabled MCP servers into opencode's global config:

maestro sync-opencode

# Auto-accept all overwrites without prompting
maestro sync-opencode -y

This writes to ~/.config/opencode/opencode.json (or opencode.jsonc, if that's the file you already have), translating each server into opencode's mcp schema — command-based servers become "type": "local" with a single command array plus environment, and HTTP servers become "type": "remote" with a url.

Existing settings are preserved: every other top-level key (model, provider, theme, ...) and any MCP servers you added by hand are left untouched. If an entry maestro manages already exists with different settings, you'll see a diff and be asked before it's replaced. Restart opencode afterwards for the changes to apply.

Note: OAuth-based servers (such as Slack) are written with their OAuth settings, but maestro can't complete the handshake for you — authenticate from within opencode. Maestro writes strict JSON, so if your config uses comments or trailing commas it will stop rather than silently drop them.

View Server Logs

View logs for a specific MCP server:

# Show available servers
maestro logs

# View last 50 lines of logs for a server
maestro logs youtrack

# View last 100 lines
maestro logs youtrack -n 100

# Follow logs in real-time (like tail -f)
maestro logs youtrack -f

# Clear all log files
maestro logs clear

Supported MCP Servers

Currently supported:

• YouTrack - JetBrains issue tracking integration

Adding New MCP Servers

To add support for a new MCP server:

1. Create a new file in src/servers/ (e.g., github.ts)
2. Implement the MCPServerDefinition interface:

   export const githubServer: MCPServerDefinition = {
     name: 'github',
     displayName: 'GitHub',
     description: 'GitHub integration',
     requiredAuth: [
       {
         key: 'token',
         label: 'Personal Access Token',
         description: 'Your GitHub PAT',
         type: 'password'
       }
     ],
     command: (config) => ['npx', '-y', '@modelcontextprotocol/server-github'],
     env: (config) => ({
       GITHUB_PERSONAL_ACCESS_TOKEN: config.auth.token
     })
   };

3. Register it in src/servers/index.ts
4. Rebuild: npm run build

Configuration

Maestro stores configuration in ~/.maestro/config.json. This includes:

• Server authentication credentials
• Server enable/disable status
• Optional server settings

Development

npm run dev     # Run in development mode
npm run build   # Build for production
npm run lint    # Run linter
npm run typecheck # Type checking

Testing

npm test         # Unit tests
npm run test:e2e # End-to-end tests for sync-cli and sync-opencode, in Docker

The end-to-end tests need Docker. They run the built binary against a fake home directory in a container and check what it wrote. See e2e/README.md for how to drive the same container by hand.

Security

• Credentials are stored locally in your home directory
• API tokens are never logged or exposed
• Each server runs in isolation with its own environment

License

MIT