Skip to main content
Glama
TerminalGravity

Claude Orchestrator MCP

by TerminalGravity
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Claude Orchestrator MCP

An MCP server for coordinating multiple Claude Code sessions across related projects. When you're working on a multi-service system with separate repos (e.g., auth service, API gateway, frontend), this orchestrator enables sessions to communicate changes, request sync points, and stay aware of what's happening in related services.

The Problem

You have 6 repos for a platform, each with its own Claude Code session. When the auth service session modifies the User schema:

  • The API gateway session has no idea

  • The frontend session keeps using old types

  • Someone has to manually copy/paste context between terminals

  • Changes get out of sync, causing integration issues

Related MCP server: session-coord-mcp

The Solution

Claude Orchestrator acts as a coordination layer:

┌─────────────────────────────────────────────────────────────┐
│                 claude-orchestrator-mcp                      │
│                                                             │
│  Sessions register → Changes detected → Updates routed      │
│                                                             │
└─────────────────────────────────────────────────────────────┘
         │           │           │           │
    ┌────┴───┐  ┌────┴───┐  ┌────┴───┐  ┌────┴───┐
    │ Auth   │  │ API    │  │ Catalog│  │Frontend│
    │Session │  │Session │  │Session │  │Session │
    └────────┘  └────────┘  └────────┘  └────────┘

Installation

# Clone and build
git clone <repo>
cd claude-orchestrator-mcp
npm install
npm run build

# Or install globally
npm install -g claude-orchestrator-mcp

Quick Start

1. Initialize configuration

# Create example topology
npx claude-orchestrator init

# Or manually create your topology
npx claude-orchestrator group create my-platform
npx claude-orchestrator member add my-platform ~/repos/auth-service --role auth
npx claude-orchestrator member add my-platform ~/repos/api-gateway --role gateway --depends-on auth
npx claude-orchestrator member add my-platform ~/repos/frontend --role frontend --depends-on gateway

2. Add to Claude Code MCP configuration

Add to your ~/.claude.json:

{
  "mcpServers": {
    "claude-orchestrator": {
      "command": "node",
      "args": ["/path/to/claude-orchestrator-mcp/dist/index.js"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "claude-orchestrator": {
      "command": "npx",
      "args": ["-y", "claude-orchestrator-mcp"]
    }
  }
}

3. Use in your Claude Code sessions

When starting work in a repo:

> Use the register_session tool with repoPath="/Users/me/repos/auth-service",
  projectGroup="my-platform", role="auth"

Check for updates from other sessions:

> Use get_cross_project_updates with my session ID

Notify others about a change:

> Use notify_related_sessions to broadcast that I modified the User schema

Configuration

The topology configuration lives at ~/.config/claude-orchestrator/topology.yml:

version: "1.0"

groups:
  my-platform:
    name: my-platform
    description: "My multi-service platform"

    members:
      - path: ~/repos/auth-service
        role: auth
        exports: [UserToken, AuthContext]

      - path: ~/repos/api-gateway
        role: gateway
        dependsOn: [auth]

      - path: ~/repos/frontend
        role: frontend
        dependsOn: [gateway]

    communicationRules:
      - when: schema_change
        from: "*"
        notify: dependents
        priority: high

      - when: breaking_change
        from: "*"
        notify: all
        priority: critical

Change Types

  • schema_change - Database/GraphQL/Protobuf schema changes

  • api_endpoint_change - Route/controller/API changes

  • type_definition_change - TypeScript/interface changes

  • config_change - Configuration file changes

  • dependency_update - package.json/requirements.txt changes

  • breaking_change - Detected via commit message patterns

  • any_change - Catch-all for any file change

Notification Targets

  • "all" - Notify all members in the group

  • "dependents" - Notify only members that depend on the source

  • ["role1", "role2"] - Notify specific roles

MCP Tools

Session Management

Tool

Description

register_session

Register this session with the orchestrator

unregister_session

Unregister when done

heartbeat

Keep session active, update current task

Cross-Project Updates

Tool

Description

get_cross_project_updates

Check for updates from related sessions

notify_related_sessions

Broadcast a change to related sessions

State Queries

Tool

Description

query_project_state

Query another project's status/changes

list_group_sessions

List all sessions in a project group

Sync Points

Tool

Description

request_sync_point

Request coordination barrier

acknowledge_sync_point

Acknowledge a sync request

get_pending_sync_points

Get pending sync requests

Topology

Tool

Description

get_topology

Get project topology configuration

CLI Commands

# Group management
claude-orchestrator group create <name>
claude-orchestrator group list
claude-orchestrator group show <name>
claude-orchestrator group delete <name>

# Member management
claude-orchestrator member add <group> <path> --role <role> --depends-on <roles>
claude-orchestrator member remove <group> <path>

# Rule management
claude-orchestrator rule add <group> --when <type> --from <roles> --notify <targets>

# Utilities
claude-orchestrator validate
claude-orchestrator init
claude-orchestrator config-path

How It Works

  1. Session Registration: Each Claude Code session registers with the orchestrator, providing its repo path, project group, and role.

  2. Change Detection: The orchestrator watches registered repos for file changes (via chokidar) and git commits (via polling). Changes are classified by type based on file patterns.

  3. Event Routing: When changes are detected, the topology manager determines which sessions should be notified based on communication rules and dependency relationships.

  4. Update Queuing: Updates are queued for target sessions. When a session calls get_cross_project_updates, it receives all pending notifications.

  5. Sync Points: Sessions can request sync points for coordinated changes. Other sessions are notified and can acknowledge before the requester proceeds.

Example Workflow

Terminal 1 (auth-service):
> Register session for auth-service in my-platform group
> [Working on User schema changes...]
> Notify related sessions: "Modified User schema, added refreshToken field"

Terminal 2 (api-gateway):
> Register session for api-gateway in my-platform group
> Check for cross-project updates
> [Receives notification about User schema change]
> "Update UserToken type to include refreshToken"

Terminal 3 (frontend):
> Register session for frontend in my-platform group
> Check for cross-project updates
> [Receives notification via gateway dependency chain]
> "Update auth context to handle new token field"

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run CLI
npm run cli -- group list

# Type check
npm run typecheck

# Run tests
npm test

License

MIT

This server cannot be installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/TerminalGravity/claude-orchestrator-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server