Skip to main content
Glama

Iris MCP

by jenova-marie
GitHub
TypeScript
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Iris MCP 🌈

Model Context Protocol server for cross-project Claude Code coordination

Iris MCP enables Claude Code instances across different project directories to communicate and coordinate. Stay in one project while asking questions to teams in other codebases.

🎯 What is Iris MCP?

Iris MCP is a revolutionary MCP server that lets Claude Code teams talk to each other. Instead of manually context-switching between projects, you can:

You (in frontend project): "Using Iris, ask the backend team what their API versioning strategy is" Claude (in frontend) → Iris MCP → Claude (in backend) → analyzes backend code → responds ↓ "The backend team uses semantic versioning with /api/v1, /api/v2 prefixes"

You never left the frontend project. Iris handled the coordination automatically.

🚀 Quick Start

Installation

# Install globally npm install -g @iris-mcp/server # Or use locally git clone https://github.com/your-org/iris-mcp cd iris-mcp pnpm install pnpm build

Configuration

Create a teams.json file (copy from src/config/teams.example.json):

{ "settings": { "idleTimeout": 300000, "maxProcesses": 10, "healthCheckInterval": 30000 }, "teams": { "frontend": { "path": "/Users/you/projects/acme-frontend", "description": "React TypeScript frontend with Tailwind", "skipPermissions": true, "color": "#61dafb" }, "backend": { "path": "/Users/you/projects/acme-backend", "description": "Node.js Express REST API", "skipPermissions": true, "color": "#68a063" }, "mobile": { "path": "/Users/you/projects/acme-mobile", "description": "React Native mobile app", "skipPermissions": true, "color": "#0088cc" } } }

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Start Using

Restart Claude Desktop and start a conversation:

> "Ask the backend team what database they use"

Claude will automatically use Iris MCP to coordinate!

🛠️ MCP Tools

teams_ask

Ask a team a question and wait for response.

{ team: "backend", question: "What database migration system do you use?", timeout: 30000 // optional, default 30s }

Response:

{ "team": "backend", "question": "What database migration system do you use?", "response": "We use Prisma for database migrations...", "duration": 2847, "timestamp": 1704067200000 }

Example prompts:

  • "Ask the backend team about their authentication strategy"

  • "Using Iris, find out from mobile team if they support push notifications"

  • "Check with frontend team what state management library they use"

teams_send_message

Send a message to another team, optionally wait for response.

{ fromTeam: "frontend", // optional toTeam: "backend", message: "Breaking change: User model now requires email field", waitForResponse: true, // optional, default true timeout: 30000 // optional }

Response (if waitForResponse = true):

{ "from": "frontend", "to": "backend", "message": "Breaking change: User model now requires email field", "response": "Acknowledged. Updating user schema and creating migration.", "duration": 3200, "timestamp": 1704067200000, "async": false }

Example prompts:

  • "Tell the backend team we're deprecating the old API endpoint"

  • "Send a message to mobile team about the new authentication flow"

  • "Coordinate with all teams to update the User model"

teams_notify

Fire-and-forget notification (queued for later).

{ fromTeam: "backend", // optional toTeam: "frontend", message: "New API endpoint available: GET /api/v2/users", ttlDays: 30 // optional, default 30 }

Response:

{ "notificationId": "abc-123-def-456", "from": "backend", "to": "frontend", "message": "New API endpoint available: GET /api/v2/users", "expiresAt": 1706745600000, "timestamp": 1704067200000 }

Example prompts:

  • "Notify all teams about the scheduled maintenance window"

  • "Send a notification to mobile team about the API changes"

teams_get_status

Get status of teams, processes, and notifications.

{ team: "backend", // optional, omit for all teams includeNotifications: true // optional, default true }

Response:

{ "teams": [ { "name": "backend", "description": "Node.js Express REST API", "path": "/Users/you/projects/acme-backend", "active": true, "processMetrics": { "pid": 12345, "status": "idle", "messagesProcessed": 47, "lastUsed": 1704067200000, "uptime": 180000, "queueLength": 0 }, "notifications": { "pending": 2, "total": 15 } } ], "pool": { "totalProcesses": 3, "maxProcesses": 10 }, "queue": { "total": 25, "pending": 2, "read": 20, "expired": 3 }, "timestamp": 1704067200000 }

Example prompts:

  • "Show me the status of all teams"

  • "Check if the backend team is currently active"

  • "How many pending notifications does frontend have?"

📁 Project Structure

iris-mcp/ ├── src/ │ ├── index.ts # MCP server entry point │ ├── config/ │ │ ├── teams-config.ts # Configuration loader with Zod validation │ │ └── teams.example.json # Example configuration │ ├── process-pool/ │ │ ├── pool-manager.ts # Process pool with LRU eviction │ │ ├── claude-process.ts # Individual Claude process wrapper │ │ └── types.ts # TypeScript interfaces │ ├── tools/ │ │ ├── teams-ask.ts # teams_ask tool │ │ ├── teams-send-message.ts │ │ ├── teams-notify.ts │ │ ├── teams-get-status.ts │ │ └── index.ts │ ├── notifications/ │ │ ├── queue.ts # SQLite notification queue │ │ └── schema.sql │ └── utils/ │ ├── logger.ts # Structured logging to stderr │ ├── errors.ts # Custom error types │ └── validation.ts # Input validation ├── teams.json # Your team configuration ├── package.json └── README.md

🏗️ Architecture

Process Pool Management

Iris maintains a pool of Claude Code processes with:

  • LRU Eviction: When pool is full, least recently used process is terminated

  • Idle Timeout: Processes automatically terminate after 5 minutes of inactivity

  • Health Checks: Regular monitoring ensures processes stay healthy

  • Connection Pooling: Reuses existing processes for 52%+ faster responses

Notification Queue

Persistent SQLite database stores notifications with:

  • 30-day retention: Automatic cleanup of old notifications

  • Status tracking: pending, read, expired

  • Team filtering: Get notifications for specific teams

  • TTL support: Configurable expiration per notification

Event System

All process events are emitted for future Intelligence Layer integration:

  • process-spawned

  • process-terminated

  • process-exited

  • process-error

  • message-sent

  • message-response

🎯 Configuration Options

Settings

{ "settings": { "idleTimeout": 300000, // 5 minutes in milliseconds "maxProcesses": 10, // Max concurrent processes "healthCheckInterval": 30000 // 30 seconds } }

Team Configuration

{ "teams": { "teamName": { "path": "/absolute/path", // Required: project directory "description": "Team description", "idleTimeout": 600000, // Optional: override global timeout "skipPermissions": true, // Optional: auto-approve Claude actions "color": "#ff6b6b" // Optional: hex color for UI (future) } } }

🔧 Development

Build

pnpm build

Watch Mode

pnpm dev

Run MCP Inspector

pnpm inspector

This opens the MCP inspector at http://localhost:5173 to test tools interactively.

Logs

All logs go to stderr in JSON format:

{"level":"info","context":"server","message":"Iris MCP Server initialized","teams":["frontend","backend","mobile"],"timestamp":"2025-01-15T10:30:00.000Z"}

🚨 Troubleshooting

"Team not found" error

  • Check that team name in teams.json matches exactly (case-sensitive)

  • Verify the path exists and is absolute

"Process failed to spawn"

  • Ensure claude-code CLI is installed and in PATH

  • Check that the team's project directory is valid

  • Try running claude-code --headless manually in the team directory

"Timeout exceeded"

  • Increase timeout parameter in tool call

  • Check if the target team's Claude process is stuck

  • View logs for error details

Database locked

  • Close other Iris MCP instances

  • Delete data/notifications.db-wal and data/notifications.db-shm

🗺️ Roadmap

✅ Phase 1: Core MCP Server (CURRENT)

  • MCP tools for team coordination

  • Process pool management

  • Notification queue

  • Configuration system

🚧 Phase 2: Web Dashboard

  • React SPA for monitoring

  • Real-time WebSocket updates

  • Team management UI

  • Analytics dashboard

See src/dashboard/README.md

🔮 Phase 3: Programmatic API

  • RESTful HTTP endpoints

  • WebSocket streaming

  • API key authentication

  • Official SDKs (TypeScript, Python)

See src/api/README.md

🔮 Phase 4: CLI

  • iris ask command

  • iris status monitoring

  • Interactive shell mode

  • Built with Ink (React for terminals)

See src/cli/README.md

🔮 Phase 5: Intelligence Layer

  • Loop detection

  • Destructive action prevention

  • Pattern recognition

  • Self-aware coordination

See src/intelligence/README.md

📚 Documentation

🤝 Contributing

Contributions welcome! This is Phase 1 - there's lots of exciting work ahead.

📄 License

MIT License - see LICENSE file for details

🌟 Why "Iris"?

Iris was the Greek goddess of the rainbow and messenger of the gods, bridging heaven and earth. Similarly, Iris MCP bridges your AI agents across project boundaries.

One messenger. Many teams. Infinite coordination.

Built with ❤️ by Jenova Marie

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables Claude Code instances across different project directories to communicate and coordinate. Stay in one project while asking questions to teams in other codebases through cross-project messaging and coordination.

  1. 🎯 What is Iris MCP?
    1. 🚀 Quick Start
      1. Installation
      2. Configuration
      3. Add to Claude Desktop
      4. Start Using
    2. 🛠️ MCP Tools
      1. teams_ask
      2. teams_send_message
      3. teams_notify
      4. teams_get_status
    3. 📁 Project Structure
      1. 🏗️ Architecture
        1. Process Pool Management
        2. Notification Queue
        3. Event System
      2. 🎯 Configuration Options
        1. Settings
        2. Team Configuration
      3. 🔧 Development
        1. Build
        2. Watch Mode
        3. Run MCP Inspector
        4. Logs
      4. 🚨 Troubleshooting
        1. "Team not found" error
        2. "Process failed to spawn"
        3. "Timeout exceeded"
        4. Database locked
      5. 🗺️ Roadmap
        1. ✅ Phase 1: Core MCP Server (CURRENT)
        2. 🚧 Phase 2: Web Dashboard
        3. 🔮 Phase 3: Programmatic API
        4. 🔮 Phase 4: CLI
        5. 🔮 Phase 5: Intelligence Layer
      6. 📚 Documentation
        1. 🤝 Contributing
          1. 📄 License
            1. 🌟 Why "Iris"?

              New MCP Servers

              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/jenova-marie/iris-mcp'

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