Multi - Agent MCP Server with Task Coordination, File Locking, Issue Tracking & Mail System in MCP Beads Village

MCP Beads Village

Beads Village is a multi-agent MCP server for task coordination and file locking between AI agents. It combines Beads issue tracking and a built-in mail system, enabling multiple agents to collaborate in the same codebase without conflicts.

Developer tools Version control #Multi-agent Collaboration #Task Coordination #File Locking #AI Agent Communication .Python

rating : 2.5 points

downloads : 7.7K

update time : 2025-12-29

Open Site

What is Beads Village?

Beads Village is a server based on the Model Context Protocol (MCP), specifically designed for multiple AI agents to work together. Imagine you have a team composed of different AI agents: one is responsible for the front-end, one for the back-end, and one for the mobile end. Without a coordination mechanism, they may modify the same file simultaneously, leading to conflicts. Beads Village solves this problem through a task queue and a file locking system, allowing AI agents to collaborate in an orderly manner like human teams.

How to use Beads Village?

Using Beads Village is very simple: First, install the necessary dependencies, and then configure the MCP server in your AI tools (such as Claude Desktop, Cursor, VS Code, etc.). After the configuration is completed, AI agents can collaborate through a standard task workflow: initialize → claim tasks → lock files → complete tasks → restart. The entire process is fully automated and does not require manual intervention.

Use cases

Beads Village is particularly suitable for the following scenarios: 1) Collaborative development of large projects by multiple AI agents; 2) Team collaboration that needs to avoid file editing conflicts; 3) AI workflows that require task assignment and progress tracking; 4) Collaborative environments across different AI tools (Claude, Cursor, Copilot, etc.).

Main Features

Intelligent Task Management

Based on the Beads issue tracking system, it supports task creation, assignment, status tracking, and completion. AI agents can automatically claim tasks, and the system ensures that only one agent processes a specific task at a time.

File Conflict Prevention

Automatically lock files before editing to prevent multiple agents from modifying the same file simultaneously. It supports temporary locking and automatic release to ensure code consistency.

Built-in Messaging System

Without the need for an external mail server, agents can directly send messages, broadcast notifications, or view their inboxes. It supports team communication and status synchronization.

Role-based Task Assignment

Supports the leader/worker model. Role tags (such as 'fe', 'be') can be added to tasks, and workers can only see tasks that match their roles.

Visual Dashboard

It has a built-in Textual TUI dashboard that displays the team status, task board, file locks, and messages in real-time. It supports click navigation and multiple filtering views.

Graph Analysis Function (Optional)

Integrates the bv binary tool to provide advanced graph analysis: key node identification, bottleneck detection, parallel execution planning, and priority recommendation.

Advantages

Zero-configuration messaging system: No need to set up an external mail server, ready to use out of the box

Fully Git-native: All data is stored in a Git repository, friendly to version control

Cross-platform compatible: Supports all mainstream AI tools and IDEs

Lightweight design: Core functions do not rely on external services, with high operating efficiency

Flexible team structure: Supports dynamic agent discovery and role assignment

Limitations

Requires Beads CLI as a pre-requisite dependency

Advanced graph analysis function requires additional installation of the bv binary tool

Currently mainly targeted at code development scenarios, with limited support for other types of collaboration

Requires all participating agents to be configured with an MCP client

How to Use

Install Pre-requisite Dependencies

First, ensure that Python and Node.js are installed on the system, and then install the Beads CLI tool.

Install Beads Village

Install globally via npm or run directly using npx. It is recommended to use npx to avoid version conflicts.

Configure Your AI Tools

According to the AI tools you use (Claude Desktop, Cursor, VS Code, etc.), edit the corresponding configuration files and add Beads Village as the MCP server.

Start the Collaborative Workflow

After the configuration is completed, AI agents can collaborate using the standard workflow: initialize → claim tasks → lock files → work → complete tasks.

Usage Examples

Multi-agent Collaborative Development of a Web Application

A front-end AI agent, a back-end AI agent, and a testing AI agent collaborate to develop a complete web application. The front-end agent is responsible for UI components, the back-end agent for APIs, and the testing agent for writing test cases.

Code Refactoring and Rewriting Project

Multiple AI agents work together to refactor a legacy codebase into a modern architecture. Different agents are responsible for different modules or layers, and conflicts are avoided through file locking.

Emergency Bug Fix Collaboration

A serious bug occurs in the production environment, and multiple AI agents participate in the fix simultaneously. Coordinated by Beads Village, the fix work is ensured to be conflict-free and quickly deployed.