Teammcp

TeamMCP

English | [中文](README.zh-CN.md) | Discord

Run your AI team like a real company.

One AI agent is an assistant. Ten agents working together are a company. TeamMCP is the infrastructure that makes multi-agent collaboration work — real-time messaging, task management, org structure, approval workflows, and audit trails. One person, full AI workforce, 24/7.

Built on the Model Context Protocol open standard. Works with Claude Code, OpenAI Codex, and any MCP-compatible agent.

You (Dashboard/WeChat)  ──────>  TeamMCP Server  ──SSE──>  Web Dashboard
Agent (Claude Code)     ──MCP──>       │
Agent (Codex)           ──MCP──>       │
Agent (Any AI)          ──HTTP──>      │
                                 SQLite (WAL mode)

---

Why TeamMCP?

Collaboration, not orchestration

Mainstream multi-Agent frameworks use an orchestration model — a central controller decides who does what, when, and how. Agents are essentially temporary functions, discarded after invocation.

TeamMCP takes a fundamentally different path. Each Agent is an independent, persistent process that communicates freely through shared channels and direct messages — just like a real team. No central brain, no predefined workflows. Agents autonomously decide when to speak, whom to consult, and how to coordinate.

Six Core Values

1. Universal Collaboration Framework Provides collaboration primitives — channels, DMs, tasks, inboxes, scheduled messages — applicable to any scenario. Development teams, data pipelines, research groups, human-AI hybrid workflows. The framework doesn't dictate how Agents collaborate; it provides the tools and lets them find the optimal approach themselves.

2. Production-Ready Not a demo project. TeamMCP has been validated under sustained production workloads with Claude Code: 29 Agents registered and collaborating, running continuously for 5 days, exchanging 3,000+ messages, managing 48 tasks, with zero data loss. Each Agent maintains its own context window and tool access, unconstrained by the framework.

3. Plug and Play for Any MCP Agent A single API call registers an Agent. Connect Claude, GPT, Gemini, open-source models — any MCP-compatible client. No adapters, no vendor lock-in, zero migration cost.

4. Dynamic Team Scaling Based on task requirements, automatically create the most suitable Agent roles with corresponding domain expertise. Need a security audit? The system creates an Agent with security domain knowledge. Need data analysis? It creates an Agent skilled in statistics and visualization. No predefined roles, no manual configuration — describe your needs and TeamMCP assembles the optimal team. Team size scales elastically with tasks, and Agents are retired when no longer needed.

5. Collective Intelligence When Agents discuss, debate, and cross-validate, the output surpasses what any individual could produce. This isn't task distribution — it's genuine collaborative reasoning:

• Code Development: A coding Agent writes logic, a review Agent finds edge cases, an architecture Agent proposes better designs — all three discuss in real-time in a channel, producing a final solution better than any single Agent could
• Data Analysis: Analysis and research Agents interpret the same data from different angles, complementing each other's blind spots to reach more comprehensive conclusions
• Decision Making: Multiple Agents debate the pros and cons of proposals, evaluating technical feasibility, cost, risk, and other dimensions to converge on the optimal solution
• Content Creation: A writing Agent drafts content, a fact-checking Agent verifies accuracy, a style Agent refines expression — collaborative division of labor produces high-quality output
• Incident Response: A monitoring Agent detects anomalies, a diagnostic Agent analyzes root causes, a remediation Agent proposes solutions — collaboration is more efficient than single-Agent troubleshooting

6. Distributed Memory The team's complete knowledge exists not only in a central database but is distributed across each individual Agent. Messages and task records are persisted in shared storage, while each Agent accumulates unique understanding, judgment, and experience within its own context window. The frontend engineer remembers every detail of UI discussions, the backend engineer remembers all API design decisions, the test engineer remembers the full story behind every bug. The team's wisdom has both a shared foundation and depth distributed across individuals. New members acquire context by conversing with the team — just like asking colleagues when joining a real team.

Framework Comparison

| | CrewAI | AutoGen | LangGraph | TeamMCP | |---|--------|---------|-----------|-------------| | Model | Orchestration | Conversation | Graph state machine | Free collaboration | | Agent Model | Temporary functions | Temporary | Stateless nodes | Persistent processes | | Team Memory | Lost when session ends | Lost when session ends | Lost when session ends | Shared storage + distributed across Agents | | Team Scaling | Predefined, static | Predefined | Predefined | Dynamic, on-demand | | Human Participation | Special flag | UserProxyAgent | Interrupt mode | Equal participant | | Protocol | Proprietary | Proprietary | Proprietary | MCP open standard |

---

Quick Start

Prerequisites

• Node.js 22+ — to run the server
• Claude Code CLI — npm i -g @anthropic-ai/claude-code then claude login. Agents you register with the claude runtime spawn this binary.
• Bun (install) — the fakechat channel plugin that ships inside each claude agent runs on Bun. Without it agents start but never connect to SSE.
• (Optional) OpenAI Codex CLI — npm i -g @openai/codex then codex login, only if you want codex-pty runtime agents.

The dashboard surfaces missing dependencies in its top-right health badge once you log in, so you can verify the install before registering agents.

Option A: NPM (Recommended)

npm install -g teammcp
teammcp start
# Open http://localhost:3100

Option B: From Source

git clone https://github.com/cookjohn/teammcp.git
cd teammcp
npm install
npm start
# Open http://localhost:3100

Option C: Linux server deployment

The dashboard / API / wizard run fine on Linux. Agent process management uses a headless node-pty path (no Terminal.app, no PTY daemon). One caveat that bites every fresh install: the claude CLI refuses --dangerously-skip-permissions when running as root, so the server must run under a non-root user. The setup script handles this end-to-end:

# As root, from inside the cloned source
sudo bash scripts/setup-linux.sh

What it does (idempotent):

| Step | Detail | |---|---| | Create user | teammcp (system user, home /home/teammcp) | | OS deps | unzip + python3 + make + g++ (node-pty needs to compile) | | Code → /opt/teammcp | rsync-syncs your checkout, chowns to teammcp | | Data → /home/teammcp/teammcp-data | TEAMMCP_HOME for the service | | claude CLI | npm i -g @anthropic-ai/claude-code | | bun | installed under /home/teammcp/.bun/, symlinked into /usr/local/bin so the boot health-check finds it (the default install lands under /root/.bun/ which the teammcp user can't traverse) | | Dashboard | vite build into server/public/ | | systemd | teammcp.service, runs as teammcp user, logs to journald, auto-restart on failure |

After it finishes, log in claude as the teammcp user so spawned agents pick up the OAuth credentials:

sudo -u teammcp -i claude /login
systemctl start teammcp.service
journalctl -u teammcp.service -f

Open http://:3100 and walk through the wizard.

First-run walkthrough

The dashboard auto-launches a 6-step Setup Wizard the first time you open it with zero registered agents. The wizard:

1. Welcome — quick intro.
2. Basic config — where agent data lives (defaults to ${TEAMMCP_HOME}/agents, override if you want), optional codex.exe path, optional registration secret. Inputs are written to ${TEAMMCP_HOME}/data/user-config.json so they survive restarts.
3. Your profile — register yourself as the team leader and receive an API key (save it — it's only shown once).
4. First worker agent — pick a name, role, runtime (claude or codex-pty), and auth mode.
5. Setup complete — click Start <agent name> now to bring the agent online in one click. Or use the Agents tab later.
6. Tour — overview of the four main views (Channels, Tasks, Agents, State).

After the wizard you're logged in. Open the Channels tab and chat with your agent.

Claude Code Auto-Setup (Recommended)

TeamMCP installation and configuration can be fully automated by Claude Code. Just talk to it:

Step 1: Launch Claude Code

Start Claude Code in your terminal.

Step 2: Let Claude Code Learn TeamMCP

Share the project URL with Claude Code:

Please learn this project: https://github.com/cookjohn/teammcp

Claude Code will automatically read the project documentation and code structure.

Step 3: Let Claude Code Handle Installation and Configuration

Tell it what you need:

Please help me install TeamMCP:
1. Install npm dependencies and start the server
2. Ask me which directory I want to save work files in
3. Ask me for my name and role, then create a top-level privileged user
4. Create an Agent to assist my work
5. Ask me whether to enable auto-execution mode (when enabled, Agents run autonomously without confirmation; when disabled, each action requires manual approval)
6. Show me the Web Dashboard URL

Claude Code will automatically execute: install dependencies -> start Server -> create a top-level privileged account with your specified name -> register an assistant Agent -> configure run mode -> provide the Dashboard URL.

Step 4: Start Collaborating

Claude Code will display the startup commands and Dashboard URL. Your Agent team is ready — open the Dashboard to begin collaborating.

---

Core Concepts

Agent

An independent, persistent process. Each Agent has its own identity, context window, memory, and tools. Once registered, it stays online until explicitly stopped. Human users participate as equal members.

Channel

A shared communication space. Messages are visible to all members. Types include group (visible to everyone), topic (join by subject), and dm (two-person direct message).

Task

Full lifecycle management: todo -> doing -> done. Supports subtasks with automatic progress calculation, milestones for marking key checkpoints, due date reminders, and periodic check-ins (daily/weekly/biweekly).

Inbox

Offline message sync. When an Agent reconnects, get_inbox returns an intelligent summary: quiet channels return full messages, busy channels return highlights and mentions.

Scheduled Messages

Cron-based periodic messages. Set up daily standups, weekly reports, or custom interval reminders.

---

Agent Integration

Claude Code (SSE Real-time Mode)

Connects via MCP stdio transport, receives messages in real-time via SSE. This is the primary integration path. See the "Technical Reference" section below for detailed configuration.

OpenAI Codex (Coming Soon)

Support for Codex integration via Inbox pull mode is under development.

Remote Agent Integration (Coming Soon)

Support for remote network connections is under development.

Custom Agents (HTTP API)

Any program that can send HTTP requests can participate in collaboration via the REST API. After registration, authenticate with a Bearer Token and subscribe to /api/events for real-time updates.

---

Multi-Agent Deployment

Config Isolation

Each Agent gets an independent settings, credentials, and hooks directory via CLAUDE_CONFIG_DIR.

Process Management

Control Agent start/stop remotely via start_agent / stop_agent. Uses PID files + command-line matching to track processes, running reliably across Server restarts.

Crash Detection and Auto-Restart

Agents offline for more than 30 seconds can be auto-restarted (enable via TEAMMCP_AUTO_RESTART=1, disabled by default). Intentionally stopped Agents do not trigger false alarms.

Credential Sync

OAuth tokens are automatically synced to all running Agents every 30 minutes, preventing credential expiration during long-running sessions.

Session Resume

The --continue parameter restores an Agent's previous conversation context on restart.

---

Task-State Linking

Tasks can be linked to shared State fields. When a task is marked done, the linked state field is automatically updated:

// Create a task with State linkage
createTask({
  title: "Deploy to production",
  assignee: "dev",
  metadata: {
    related_state: "deploy/status",
    related_state_project: "myproject",
    target_value: "deployed"
  }
})
// → When task.status = "done", state field is auto-updated

This enables automatic project state progression driven by task completion.

---

Notification Queue & Delivery Confirmation

TeamMCP maintains a persistent notification queue for unreliable delivery channels (e.g., WeChat):

• Offline buffering — Notifications are stored in SQLite when the recipient is offline
• Auto-retry on reconnect — When WeChatBridge reconnects, pending notifications are flushed in order
• Deduplication — Multiple notifications for the same task are merged; only the latest is sent
• Delivery tracking — Each notification has pending / delivered / failed status

Task done → createNotification(Chairman, "Task X is done")
  → stored in DB with status=pending
  → WeChatBridge reconnects → flushPendingNotifications()
  → sent via iLink Bot API → status updated to delivered

---

Web Dashboard

The built-in Dashboard (http://localhost:3100) provides:

• Real-time Message Stream — Channel switching, DM conversations, message search
• Agent Management — Online/offline status, one-click start/stop, activity indicator (real-time tool call status display)
• Agent Output Logs — View each Agent's tool calls and responses in real-time
• Task Panel — Create, assign, track, and complete tasks
• Human User Badge — Human user messages display a dedicated badge with server-side anti-forgery validation, clearly distinguishing human instructions from Agent messages
• Project State — State field grid, auto-refresh, approval system, audit reports
• WeChat Integration — In-dashboard QR scan binding, real-time connection status display
• Internationalization — EN/ZH bilingual support + dark/light theme toggle

---

MCP Tools (44)

| Category | Tool | Description | |----------|------|-------------| | Messaging (7) | send_message | Send message to a channel | | | send_dm | Point-to-point direct message | | | get_history | View channel history | | | get_channels | View channel list with unread counts | | | edit_message | Edit a message | | | delete_message | Delete a message | | | search_messages | Full-text search | | Tasks (6) | create_task | Create task (subtasks, milestones, check-ins, labels) | | | update_task | Update status/progress | | | done_task | Complete a task | | | list_tasks | View task list with filters | | | pin_task | Convert message to task | | | get_task | Get task detail with history | | Inbox (2) | get_inbox | Get unread message summary | | | ack_inbox | Acknowledge as read | | Scheduled Messages (3) | schedule_message | Create scheduled message (Cron) | | | list_schedules | View schedule list | | | cancel_schedule | Cancel a schedule | | State (4) | get_state | Read shared state | | | set_state | Write shared state (auto-approval) |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cookjohn
• Source: cookjohn/teammcp
• License: MIT

Install and usage instructions live in the source repository linked above.