Installation

This guide will walk you through installing the Orchestre MCP server and configuring it with Claude Code. The entire process takes about 5-10 minutes.

Installation Steps

Step 1: Clone the Repository

First, clone the Orchestre repository to your local machine:

# Clone the repository
git clone https://github.com/orchestre-dev/mcp.git

# Navigate to the project directory
cd mcp

Step 2: Install Dependencies

Install the required Node.js packages:

# Install dependencies
npm install

This will install all necessary packages including:

• TypeScript for type safety
• Zod for schema validation
• MCP SDK for Claude Code integration
• Various AI SDK clients

Step 3: Configure Environment

Create your environment file with API keys:

# Copy the example environment file
cp .env.example .env

# Edit .env with your favorite editor
# Add your API keys:
# GEMINI_API_KEY=your_gemini_key_here
# OPENAI_API_KEY=your_openai_key_here

💡 Quick Tip

Don't have API keys yet? Check the prerequisites guide for instructions on obtaining them.

Step 4: Build the Project

Build the TypeScript code:

# Build the project
npm run build

This compiles the TypeScript source code into JavaScript that can be executed by Node.js.

Step 5: Configure Claude Code

Now we need to tell Claude Code about Orchestre. You have two options:

Option 1: Using Claude Code CLI (Recommended)

# Get the absolute path to your installation
cd /path/to/mcp
ORCHESTRE_PATH=$(pwd)

# Add Orchestre to Claude Code
claude mcp add orchestre \
  -e GEMINI_API_KEY=your_gemini_key_here \
  -e OPENAI_API_KEY=your_openai_key_here \
  -- node $ORCHESTRE_PATH/dist/index.js

Option 2: Manual Configuration

Edit your Claude Code configuration file directly. The location varies:

OS	Config File Location
macOS/Linux	~/.claude.json
Windows	%USERPROFILE%\.claude.json
WSL	Inside your Linux home directory

Add Orchestre to the mcpServers section:

{
  "mcpServers": {
    "orchestre": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "OPENAI_API_KEY": "your_openai_key_here"
      }
    }
  }
}

⚠️ Important: Use Absolute Paths

Replace /absolute/path/to/mcp with the actual path to your Orchestre installation. For example:

• macOS/Linux: /Users/yourname/projects/mcp/dist/index.js
• Windows: C:\\Users\\yourname\\projects\\mcp\\dist\\index.js

Note the double backslashes for Windows paths!

Step 6: Restart Claude Code

After saving the configuration:

1. Quit Claude Code completely (Cmd+Q on macOS, Alt+F4 on Windows)
2. Start Claude Code again
3. Check for Orchestre in the MCP tools list

Verifying Installation

Check MCP Server Status

In Claude Code, check that Orchestre is connected:

/mcp

This will show all connected MCP servers. You should see Orchestre listed as "Connected".

Check Available Commands

With Orchestre v5.0+, commands are available as native MCP prompts. You can verify by:

/orchestre:create (MCP)

This should show the create command interface. All Orchestre commands are now available immediately without any installation!

Test Basic Commands

Try a simple command to ensure everything is working:

/orchestre:orchestrate (MCP)
# Then provide: "Build a simple todo app"

This should analyze your requirements and generate a development plan.

Native MCP Prompts (v5.0+)

🎉 New in v5.0: No Installation Required!

Starting with Orchestre v5.0, all commands are available as native MCP prompts. This means:

• ✅ No files to install - Commands work immediately
• ✅ Always up-to-date - Server improvements available instantly
• ✅ Clean projects - No .claude/commands/ directories
• ✅ Better performance - Direct protocol communication

You can immediately use all Orchestre commands:

• /orchestre:create (MCP) - Start a new project with a template
• /orchestre:orchestrate (MCP) - Analyze and plan your project
• /orchestre:execute-task (MCP) - Execute tasks with context awareness
• /orchestre:security-audit (MCP) - Comprehensive security analysis
• And all other essential commands!

💡 For Users Upgrading from v4

If you're upgrading from Orchestre v4 or earlier:

1. You can safely delete any .claude/commands/ directories
2. The install_commands tool is now deprecated
3. All commands work through the MCP protocol

Installation Script (Optional)

For automated installation, save this as install-orchestre.sh:

#!/bin/bash

echo "🎭 Installing Orchestre V3..."

# Clone repository
echo "📦 Cloning repository..."
git clone https://github.com/orchestre-dev/mcp.git
cd mcp

# Install dependencies
echo "📚 Installing dependencies..."
npm install

# Copy environment file
echo "🔐 Setting up environment..."
cp .env.example .env
echo "⚠️  Remember to add your API keys to .env!"

# Build project
echo "🔨 Building project..."
npm run build

# Get absolute path
ORCHESTRE_PATH=$(pwd)

# Show configuration snippet
echo ""
echo "✅ Installation complete!"
echo ""
echo "📝 Add this to your Claude config file:"
echo ""
cat << EOF
{
  "mcpServers": {
    "orchestre": {
      "type": "stdio",
      "command": "node",
      "args": ["${ORCHESTRE_PATH}/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_key_here",
        "OPENAI_API_KEY": "your_openai_key_here"
      }
    }
  }
}
EOF

Troubleshooting Installation

MCP Server Not Found

Problem: Claude Code doesn't show Orchestre tools

Solutions:

1. Check config file syntax (valid JSON)
2. Verify absolute paths are correct
3. Ensure Claude Code was fully restarted
4. Check Claude logs: ~/Library/Logs/Claude/mcp*.log

Build Errors

Problem: npm run build fails

Solutions:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build

API Key Issues

Problem: "Invalid API key" errors when using tools

Solutions:

1. Verify keys in both .env and Claude config
2. Check for extra spaces or quotes
3. Ensure keys have proper permissions/credits

Path Issues on Windows

Problem: "Cannot find module" errors

Solution: Use forward slashes or double backslashes:

// ❌ Wrong
"args": ["C:\Users\name\orchestre\dist\server.js"]

// ✅ Correct (double backslashes)
"args": ["C:\\Users\\name\\orchestre\\dist\\server.js"]

// ✅ Also correct (forward slashes)
"args": ["C:/Users/name/orchestre/dist/server.js"]

Updating Orchestre

To update to the latest version:

# Navigate to Orchestre directory
cd /path/to/orchestre

# Pull latest changes
git pull origin main

# Install any new dependencies
npm install

# Rebuild
npm run build

# Restart Claude Code

Next Steps

Congratulations! Orchestre is now installed and configured. Ready to create your first project?

🚀 First Project

Create your first Orchestre project

💡 Core Concepts

Understand how Orchestre works

📚 Tutorials

Learn through hands-on examples

Quick Reference Card

Save this for easy reference:

# Orchestre Quick Reference
Repository: https://github.com/orchestre-dev/mcp
Config Location: ~/.claude.json (varies by OS)
MCP Status Check: /mcp

# Essential Commands (v5.0+ Native MCP Prompts):
/create [template] [name]     # Create new project
/orchestrate [requirements]   # Analyze and plan
/execute-task [task]         # Execute specific task
/security-audit              # Security vulnerability detection
/document-feature            # Create contextual documentation

# Need help?
Documentation: https://orchestre.dev/
GitHub Issues: https://github.com/orchestre-dev/mcp/issues