Project Brain MCP Server — Plug & Play PM for AI Development

Yes, this is an MCP (Model Context Protocol) server!

Plug it in and go! Project Brain MCP Server provides a complete project management system for AI-assisted development. Works standalone with local storage or connects to a remote backend.

📦 Installation

# Global install
npm install -g project-brain-mcp-server

# Or use npx (no install needed)
npx project-brain-mcp-server

# Or install locally
npm install project-brain-mcp-server

🎯 What is MCP?

MCP = Model Context Protocol — A standard protocol that lets AI tools (Claude, ChatGPT, etc.) interact with external systems.

This MCP server exposes project management tools so AI agents can:

• ✅ Create and manage tasks
• ✅ Track conversations
• ✅ Make decisions
• ✅ Export context for handoff

🚀 Quick Start (Plug & Play)

Option 1: Local Storage (No Backend Required)

cd mcp-server
npm install
npm run build

That's it! The server uses local file storage by default. Data is stored in ~/.project-brain/data.json.

Option 2: Remote Backend

Set environment variables:

export PROJECT_BRAIN_URL="https://your-backend.com"
export PB_STORAGE_TYPE="remote"
export PB_PROJECT_ID="your-project-id"  # Optional

📦 Installation

For Cursor IDE

See CURSOR_INTEGRATION.md for complete Cursor setup guide.

Quick setup:

1. Build: npm install && npm run build
2. Add to Cursor MCP config (check CURSOR_INTEGRATION.md for config location)
3. Restart Cursor
4. Ask Cursor: "What Project Brain tools are available?"

For Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "project-brain": {
      "command": "node",
      "args": ["/path/to/project-brain-ai/mcp-server/dist/server.js"],
      "env": {
        "PB_STORAGE_TYPE": "local",
        "PB_PROJECT_NAME": "My Project"
      }
    }
  }
}

For Other MCP Clients

Point your MCP client to:

node /path/to/project-brain-ai/mcp-server/dist/server.js

Task Dashboard

Modern React Dashboard (Recommended):

cd dashboard
npm install
npm run dev

Then open http://localhost:3000 in your browser.

Legacy Simple Dashboard:

cd mcp-server
npm run dashboard

Then open http://localhost:3001/dashboard-legacy in your browser.

See dashboard/README.md for complete dashboard documentation.

🎯 Features

✅ Task Management — Create, update, complete tasks
✅ Conversation Tracking — Log and retrieve conversations
✅ Decision Tracking — Track AI vs human decisions
✅ Drift Prevention — Get task context to keep agents focused
✅ AI Export Formats — Export data in AI-friendly formats (markdown, chat, plain text)
✅ Task Dashboard — Visual dashboard to track tasks, tokens, and costs
✅ Zero Setup — Works out of the box with local storage

🛠️ Available Tools

Project Management

• pb_create_project — Create a new project
• pb_get_project — Get project details
• pb_list_projects — List all projects

Task Management

• pb_create_task — Create a new task
• pb_get_task — Get task details
• pb_update_task_status — Update task status
• pb_complete_task — Mark task as done
• pb_get_next_task — Get next task to work on
• pb_list_tasks — List tasks for a project

Conversation Management

• pb_create_conversation — Create a conversation
• pb_log_message — Log a message
• pb_get_conversation_messages — Get messages (rebuild context)
• pb_get_conversation_summary — Get conversation summary

Decision Management

• pb_request_decision — Request a decision
• pb_answer_decision — Answer a decision
• pb_get_task_decisions — Get decisions for a task

Context & Drift Prevention

• pb_get_task_context — Get full task context (task, conversations, decisions)

AI Export (Handoff to Any AI Agent)

• pb_export_context_for_ai — Export task context in AI-friendly format (markdown/chat/plain)
• pb_export_conversation_for_ai — Export conversation ready to paste into any AI tool
• pb_export_task_for_ai — Export task with full context
• pb_export_project_for_ai — Export entire project context

📊 Data Storage

Local Storage (Default)

Data is stored in ~/.project-brain/data.json (or PB_DATA_DIR if set).

Pros:

• ✅ Zero setup
• ✅ Works offline
• ✅ Private (local only)
• ✅ Fast

Cons:

• ❌ Single machine only
• ❌ No sync across devices

Remote Storage

Set PB_STORAGE_TYPE=remote and PROJECT_BRAIN_URL to use a backend API.

Pros:

• ✅ Sync across devices
• ✅ Team collaboration
• ✅ Centralized data

Cons:

• ❌ Requires backend setup
• ❌ Network dependency

⚙️ Configuration

Environment variables:

| Variable | Default | Description | |----------|---------|-------------| | PB_STORAGE_TYPE | local | Storage type: local or remote | | PB_DATA_DIR | ~/.project-brain | Local storage directory | | PROJECT_BRAIN_URL | - | Backend API URL (required for remote) | | PB_PROJECT_ID | - | Default project ID (auto-created if not set) | | PB_PROJECT_NAME | Default Project | Default project name |

📝 Example Usage

Create a Task

{
  "tool": "pb_create_task",
  "arguments": {
    "title": "Fix login bug",
    "description": "Users can't log in with OAuth",
    "type": "bug",
    "status": "todo"
  }
}

Complete a Task

{
  "tool": "pb_complete_task",
  "arguments": {
    "taskId": "task-123",
    "notes": "Fixed OAuth redirect issue"
  }
}

Get Task Context (Drift Prevention)

{
  "tool": "pb_get_task_context",
  "arguments": {
    "taskId": "task-123"
  }
}

Export Context for AI (Handoff to Any Agent)

{
  "tool": "pb_export_context_for_ai",
  "arguments": {
    "taskId": "task-123",
    "format": "markdown"
  }
}

Returns formatted markdown ready to paste into ChatGPT, Claude, Gemini, etc.:

# Task: Fix login bug

**Status:** in-progress

## Open Decisions

### 1. Which OAuth version?
**Options:**
- OAuth 2.0
- OAuth 1.0

See AI_EXPORT.md for complete export guide.

Rebuild Conversation Context

{
  "tool": "pb_get_conversation_messages",
  "arguments": {
    "conversationId": "conv-123",
    "limit": 50
  }
}

🔄 Migration

From Local to Remote

1. Export local data from ~/.project-brain/data.json
2. Import into your backend
3. Set PB_STORAGE_TYPE=remote and PROJECT_BRAIN_URL

From Remote to Local

1. Export data from backend API
2. Set PB_STORAGE_TYPE=local
3. Data will be stored locally

🐛 Troubleshooting

Data Not Persisting

• Check PB_DATA_DIR permissions
• Ensure ~/.project-brain directory exists and is writable

Remote Storage Not Working

• Verify PROJECT_BRAIN_URL is correct
• Check network connectivity
• Ensure backend API is running

Tools Not Available

• Rebuild: npm run build
• Restart MCP client
• Check server logs

📚 Related Documentation

• AI_EXPORT.md — Export data in AI-friendly formats for handoff
• PM_GUIDE.md — Complete PM workflow guide
• PROJECT_BRAIN.md — Project history and architecture
• ENHANCEMENTS.md — Feature enhancements
• DATA_HANDLING.md — Data storage architecture

🎉 That's It!

Plug it in, configure it (or don't - it works out of the box), and start managing your AI-assisted development projects!