fuzemobi/ChatDevMCP

🏢 ChatDev MCP: Virtual Software Development Team

Give Claude access to an entire AI-powered software development company. ChatDev uses specialized AI agents (CEO, CTO, Programmer, Designer, Tester) to autonomously design, build, test, and document complete software products through multi-agent collaboration.

✨ Features

• 🤖 Multi-Agent Team: CEO, CTO, CPO, Programmer, Designer, Tester, Reviewer working together
• 🔄 Full Development Lifecycle: From requirements analysis to testing and documentation
• 🎯 Natural Language Input: Describe your software idea and watch the team build it
• 📦 Complete Project Output: Source code, documentation, tests, and assets
• 🔍 Transparent Process: Monitor team conversations and decision-making in real-time
• 🚀 Zero Configuration: Works out of the box with Claude Desktop and Claude Code

📋 Prerequisites

• OpenAI API Key: Get one here
• Git: Required for project initialization
• Claude Desktop or Claude Code: Download here

🚀 Quick Start

Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the ChatDev MCP server:

{
  "mcpServers": {
    "chatdev": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fuzemobi/ChatDevMCP.git", "chatdev-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

1. Go to Settings → Extensions → MCP Servers
2. Click Add Server
3. Configure:
   • Command: uvx
   • Args: ["--from", "git+https://github.com/fuzemobi/ChatDevMCP.git", "chatdev-mcp"]
   • Env: OPENAI_API_KEY = sk-your-key-here
4. Click Save
5. Reload Claude Code

🎮 Basic Usage

Simply describe what you want to build in natural language:

Use chatdev_start_build to create a todo app with add/edit/delete tasks,
mark complete, filter by status, local storage, and modern UI.

Project Name: TodoApp

Monitor progress:

Get status of project abc-123

Retrieve the generated code:

Get artifacts from project abc-123

View all projects:

List all ChatDev projects

🛠️ Available Tools

💡 Example Projects

🎮 Games

2048 Puzzle Game

Create a 2048 puzzle game with 4x4 grid, smooth tile animations, arrow key controls,
score tracking, best score persistence, game over detection, restart button, and
modern UI with color-coded tiles.

Project Name: Game2048

Gomoku (Five in a Row)

Build a Gomoku game with 15x15 board, two-player mode, click to place stones,
win detection for 5 in a row (horizontal, vertical, diagonal), turn indicator,
restart functionality, and traditional board styling.

Project Name: Gomoku

Flappy Bird Clone

Create a Flappy Bird game with tap/spacebar controls, procedurally generated pipes,
score counter, collision detection, game over screen with restart, and responsive
canvas rendering.

Project Name: FlappyBird

🧮 Productivity Tools

Advanced Calculator

Create a calculator with basic operations (+, -, *, /), scientific functions
(sin, cos, tan, sqrt, pow, log), memory functions (M+, M-, MR, MC),
keyboard support, calculation history with scrollback, clear and backspace buttons,
and responsive layout.

Project Name: Calculator

Expense Tracker

Build an expense tracking app with add/edit/delete expenses, categories
(food, transport, entertainment, bills, etc.), date picker, monthly/yearly summaries,
filter by category and date range, pie/bar charts for spending breakdown,
local storage persistence, and CSV export.

Project Name: ExpenseTracker

Note Taking App

Create a notebook application with create/edit/delete notes, rich text editor
with formatting (bold, italic, lists, headings), organize by folders and tags,
full-text search, auto-save, dark/light theme toggle, export to PDF/Markdown,
and local storage.

Project Name: NotebookApp

Password Generator

Build a secure password generator with configurable length (8-64 chars),
options for uppercase/lowercase/numbers/symbols, strength indicator,
copy to clipboard, generate multiple passwords, password history,
and exclude ambiguous characters option.

Project Name: PasswordGen

🛠️ Utilities

Markdown to HTML Converter

Create a markdown converter with live preview pane, support for standard markdown
syntax, syntax highlighting for code blocks, GitHub-flavored markdown support,
export to HTML file, copy HTML output, import .md files, and responsive split-pane layout.

Project Name: MarkdownConverter

File Organizer CLI

Build a CLI file organizer that scans directories, organizes files by type
(Documents, Images, Videos, Audio, Archives), handles duplicates with rename,
dry-run mode to preview changes, undo functionality, operation logging,
and configuration file for custom rules.

Project Name: FileOrganizer

Personal Finance Dashboard

Create a money control dashboard with income/expense tracking, budget planning
by category, visual charts (pie, bar, line), monthly comparison view,
savings goals tracker, CSV import/export, multi-currency support,
and responsive design.

Project Name: MoneyControl

🎨 Graphics & Design

Drawing Canvas

Build a drawing application with freehand drawing, shapes (rectangle, circle, line),
color picker with custom palette, brush size controls, eraser tool, undo/redo
(up to 20 steps), save as PNG, layer opacity, and clear canvas button.

Project Name: ArtCanvas

Pixel Art Editor

Create a pixel art sprite editor with grid-based canvas (16x16, 32x32, 64x64),
pixel-by-pixel drawing, color palette management with save/load, tools (pencil, fill, eraser),
layer support, animation frame preview, onion skinning, and export as PNG sprite sheet.

Project Name: SpriteMaker

🌐 Web Applications

SaaS Landing Page

Build a responsive landing page with hero section and CTA, features section
(6 key features with icons), pricing table (3 tiers with toggle annual/monthly),
testimonials carousel, FAQ accordion, contact form with validation,
smooth scroll navigation, mobile-responsive design, and modern gradient color scheme.

Project Name: LandingPage

E-Commerce Product Page

Create a product page with image gallery and zoom, thumbnail navigation,
product details tabs (Description, Specifications, Reviews), size/color selector,
quantity controls, add to cart button with animation, related products section,
social share buttons, star rating system, and responsive layout.

Project Name: ProductPage

Blog Platform

Build a simple blog with homepage post list, individual post pages with comments,
categories and tags with filtering, search functionality, RSS feed generation,
admin panel for CRUD operations, markdown support for posts, image upload,
draft/publish workflow, and responsive design.

Project Name: BlogPlatform

🔌 APIs & Backend

REST API for Task Management

Create a task management API with endpoints (GET, POST, PUT, DELETE) for tasks,
user authentication with JWT tokens, SQLite database, input validation with error messages,
rate limiting (100 req/min), CORS support, comprehensive error handling,
include Postman collection, OpenAPI documentation, and unit tests with pytest.

Project Name: TaskAPI

Analytics Dashboard

Build a sales analytics dashboard with metric cards (revenue, orders, customers, conversion),
line chart for trends over time, bar chart for category comparison,
pie chart for customer segment breakdown, sortable data table with pagination,
date range picker with presets, CSV export, dark/light theme toggle,
and responsive grid layout.

Project Name: AnalyticsDashboard

🔧 Browser Extensions

Pomodoro Timer

Create a Chrome extension with 25-minute work / 5-minute break cycles,
desktop notifications, session counter and history, pause/resume functionality,
customizable work/break durations, sound alerts (optional), badge counter on icon,
keyboard shortcuts, and options page for settings.

Project Name: PomodoroExtension

📝 Writing Effective Task Descriptions

✅ Good Example

Build a contact form with:
- Fields: name (required), email (required with regex validation),
  phone (formatted as XXX-XXX-XXXX), message (500 char limit with counter)
- Real-time validation showing error messages below fields
- Loading spinner during submission
- Success toast notification with auto-dismiss
- Error handling with retry option
- Mobile-responsive layout (stacked on mobile, side-by-side on desktop)
- ARIA labels and keyboard navigation for accessibility
- Submit disabled until all required fields valid

Project Name: ContactForm

❌ Too Vague

Make a contact form

Project Name: ContactForm

🎯 Key Components

Include these in your task description:

1. Core Features: What the software must do
2. UI/UX Details: Layout, styling, interactions, animations
3. Data Management: How data is stored/retrieved (localStorage, API, database)
4. User Flows: Step-by-step interactions
5. Technical Requirements: Browser support, responsiveness, accessibility
6. Constraints: Performance needs, file size limits, etc.

📋 Template

Create a [TYPE] with:
- Feature 1: [specific details with acceptance criteria]
- Feature 2: [specific details with acceptance criteria]
- Feature 3: [specific details with acceptance criteria]
- UI: [layout, colors, typography, responsive breakpoints]
- Data: [storage method, data structure, persistence]
- Performance: [loading time, file size, optimization needs]
- Accessibility: [WCAG compliance, keyboard navigation, screen readers]

Project Name: [ProjectName]

🏗️ About ChatDev

ChatDev simulates a complete software company using the waterfall development model:

The Team:

• 👔 CEO: Project oversight and decision-making authority
• 💻 CTO: Technical architecture and framework selection
• 📊 CPO: Product requirements and feature definition
• 🧑‍💻 Programmer: Code implementation
• 🎨 Designer: UI/UX design and visual assets
• 🧪 Tester: Quality assurance and test creation
• 👀 Reviewer: Code review and improvement suggestions

Development Phases:

1. Demand Analysis (5-10% of time)

   • Team discusses and clarifies requirements
   • CEO and CPO define scope and priorities

2. Language Selection (5% of time)

   • CTO chooses programming language and frameworks
   • Technical stack decisions

3. Design (15-20% of time)

   • System architecture design
   • UI/UX mockups and specifications
   • Database schema planning

4. Coding (40-50% of time)

   • Programmer implements features
   • Designer creates visual assets
   • Iterative development with internal reviews

5. Testing (15-20% of time)

   • Tester writes and executes test cases
   • Bug identification and fixes
   • Quality validation

6. Documentation (10% of time)

   • User guides and README
   • API documentation
   • Developer documentation

Typical Timeline: 5-15 minutes depending on project complexity

🔧 Configuration

Environment Variables

Add to the env section in your MCP configuration:

{
  "env": {
    "OPENAI_API_KEY": "sk-your-key-here",
    "CHATDEV_WORKSPACE": "/custom/path/to/projects",
    "CHATDEV_MODEL": "gpt-4",
    "CHATDEV_MAX_CONCURRENT": "3"
  }
}

Development Modes

Specify in the config parameter of chatdev_start_build:

• Default: Standard multi-agent workflow (recommended)
• Art: Enhanced focus on visual design and graphic assets
• Human: Human-Agent-Interaction mode (allows feedback during development)

Example:

{
  "task": "Create a beautiful portfolio website...",
  "project_name": "Portfolio",
  "config": "Art"
}

💡 Tips & Best Practices

📊 Monitor Progress: Check status every 5-10 minutes. The team conversations reveal their reasoning and implementation decisions.

🎯 Start Simple: Begin with smaller projects (calculators, to-do lists) to understand ChatDev's capabilities before tackling complex applications.

🔍 Review Team Logs: The development team's conversation logs provide insights into:

• Why they chose specific technologies
• How they solved technical challenges
• What trade-offs they considered

🔄 Iterate on Results: If the output isn't perfect, start a new build with refined requirements based on what you learned.

📦 Complete Projects: ChatDev generates:

• Source code (fully commented)
• README with usage instructions
• Documentation files
• Test files (when applicable)
• Asset files (images, styles, etc.)

⚡ Performance Expectations:

• Simple apps (calculator, to-do): 5-8 minutes
• Medium complexity (blog, dashboard): 8-12 minutes
• Complex apps (multi-feature platforms): 12-18 minutes

🚨 Troubleshooting

Server won't start

• Verify your OpenAI API key is correct
• Check internet connectivity
• Ensure Git is installed: git --version
• Review logs at ~/Library/Logs/Claude/mcp*.log (macOS)

Project stuck in "running" status

• Check OpenAI API rate limits and quota
• Verify sufficient API credits
• Check status logs for error messages

Build fails or incomplete

• Review error in chatdev_get_status output
• Ensure task description is clear and feasible
• Avoid extremely complex multi-system projects
• Check that all required dependencies are available

"Connection refused" or MCP errors

• Restart Claude Desktop/Claude Code
• Verify MCP server configuration JSON syntax
• Check that uvx is installed: uvx --version
• Try manual installation if uvx fails

Generated code doesn't work

• Review the team's assumptions in conversation logs
• Check if requirements were ambiguous
• Provide more specific technical constraints
• Try again with clarified requirements

📚 What You Get

Each ChatDev project includes:

• Source Code: Complete, commented implementation
• README.md: Project overview and usage instructions
• Documentation: User guides and API docs (when applicable)
• Tests: Test files for quality assurance
• Assets: Images, icons, stylesheets
• Logs: Full team conversation history showing development process

All files are organized in a standard project structure ready to use or further customize.

🔗 Links

• GitHub Repository
• ChatDev Project
• MCP Protocol Documentation
• OpenAI API

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• ChatDev - The multi-agent software development framework
• Anthropic MCP - Model Context Protocol
• OpenAI - Language models powering the agents

Built with ❤️ by the community. Contributions welcome!