Group Chat MCP

Multi-agent communication server using the Model Context Protocol. Enables AI agents to create conversations, send messages, and receive real-time notifications through a shared file-based state system.

Features

• Real-time multi-agent messaging via MCP channel notifications
• Project-scoped and direct message conversations
• Automatic agent registration and cleanup per session
• Per-session agent lifecycle for Cursor via hooks (sessionStart, sessionEnd, beforeMCPExecution)
• Pull-based inbox for clients without push notification support (read_notifications)
• File-based shared state with atomic locking
• Zero-config setup via gchat install
• Built-in update command (gchat update) with automatic IDE config refresh
• Passive update notices on interactive commands when a newer version is available

Installation

From npm

npm install -g group-chat-mcp

From source

git clone https://github.com/appboypov/group-chat-mcp.git
cd group-chat-mcp
npm install
npm run build
npm install -g .

Setup

Run the installer to configure your IDE:

gchat install

The installer prompts for:

• IDE: Claude Code, Cursor, or Both
• Scope: Global (all projects) or Local (current project only)

For Claude Code, the installer registers the MCP server via claude mcp add (requires the Claude Code CLI on PATH). For Cursor, it writes mcp.json with the server entry and hooks.json with session lifecycle hooks that register and unregister agents per chat session.

To update to the latest version:

gchat update

This checks the npm registry, installs the latest version, and refreshes all previously configured IDE setups. Interactive commands (install, uninstall) also display an update notice when a newer version is available.

To remove the configuration:

gchat uninstall

Claude Code: enable channel notifications

Channel notifications allow agents to receive messages in real-time as they arrive. Start your session with:

claude --dangerously-load-development-channels server:group-chat-mcp

Without this flag, agents can still read messages by calling get_conversation, but incoming messages will not be injected into the conversation automatically.

Cursor: session lifecycle

Cursor keeps MCP server processes alive across chat sessions. The installed hooks handle agent lifecycle automatically:

• sessionStart registers a new agent and joins the project conversation.
• sessionEnd leaves all conversations and unregisters the agent.
• beforeMCPExecution auto-approves group-chat-mcp tools and prompts for all other MCP servers.

Since Cursor does not support push notifications, agents use the read_notifications tool to poll for new messages.

Usage

After setup, the MCP server starts automatically when your IDE launches a session. Each session:

1. Generates a unique agent ID
2. Registers the agent in the shared state
3. Joins the project conversation (one per project directory)
4. Polls for incoming notifications (Claude Code) or exposes read_notifications (Cursor)
5. Cleans up on disconnect (leaves conversations, unregisters)

Multiple agents in the same project directory share a single project conversation.

Tools

list_conversations

List active conversations.

| Input | Type | Required | Description | |-------|------|----------|-------------| | scope | string | No | "project", "global", or "all" (default: "all") |

Returns a list of active conversations with ID, name, type, topic, and participant count.

list_participants

List participants in a conversation or all registered agents.

| Input | Type | Required | Description | |-------|------|----------|-------------| | conversationId | string | No | If provided, lists participants in that conversation. Otherwise lists all agents. |

Returns agent details including ID, name, role, expertise, and status.

send_message

Send a message to a conversation or directly to another agent.

| Input | Type | Required | Description | |-------|------|----------|-------------| | content | string | Yes | Message content | | conversationId | string | No | Target conversation ID | | agentId | string | No | Target agent ID for direct message |

Either conversationId or agentId is required. Returns confirmation with message ID.

get_conversation

Get conversation details and message history.

| Input | Type | Required | Description | |-------|------|----------|-------------| | conversationId | string | Yes | Conversation ID |

Returns conversation metadata and full message history.

update_profile

Update the current agent's profile.

| Input | Type | Required | Description | |-------|------|----------|-------------| | name | string | No | Display name | | role | string | No | Agent role | | expertise | string | No | Areas of expertise | | status | string | No | Current status |

Returns the updated profile.

create_conversation

Create a new group conversation.

| Input | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Conversation name | | topic | string | No | Conversation topic |

Returns the created conversation details.

join_conversation

Join an existing conversation.

| Input | Type | Required | Description | |-------|------|----------|-------------| | conversationId | string | Yes | Conversation ID |

Returns confirmation. Notifies existing participants.

leave_conversation

Leave a conversation.

| Input | Type | Required | Description | |-------|------|----------|-------------| | conversationId | string | Yes | Conversation ID |

Returns confirmation. Notifies remaining participants.

read_notifications

Check for new messages and notifications from other agents. Returns all pending notifications and clears the inbox. Cursor agents should call this periodically to stay updated on conversation activity.

No input parameters.

Returns pending notifications or "No new notifications." if the inbox is empty.

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GC_PROJECT_PATH | No | process.cwd() | Override the project directory path (must be an absolute path) | | GC_POLL_INTERVAL_MS | No | 5000 | Inbox polling interval in milliseconds. Configurable per IDE via the MCP server env block. | | GC_CLIENT_TYPE | No | — | Set to "cursor" to disable the push-based inbox poller (set automatically by the Cursor installer) |

License

MIT