MCP Hub
Back to servers

project-brain-mcp-server

Project management MCP server for AI-assisted development. Track tasks, conversations, decisions, token usage, and costs.

npm90/wk
AI & MLProductivity
Updated
Feb 17, 2026
View Source
Claim this server

Quick Install

npx -y project-brain-mcp-server

Project Brain MCP (Free Tier)

Coordinate multiple AI agents across your codebase

While Cursor handles one file and Claude Code helps with another, Project Brain tracks what each agent worked on, prevents conflicts, and makes it easy to hand off context between tools.

License: MIT Node Version MCP Compatible

What is Project Brain?

When you use multiple AI coding agents (Claude Desktop, Cursor, GitHub Copilot), it's hard to track:

  • ❌ What each agent is working on
  • ❌ Which conversations led to which code changes
  • ❌ Important decisions made during development
  • ❌ How to hand off context between agents

Project Brain solves this by:

  • ✅ Task coordination - Assign work to specific agents
  • ✅ Conversation search - Find past discussions instantly 🆕
  • ✅ Decision tracking - Record architectural choices
  • ✅ Context handoff - Export/import complete project state 🆕
  • ✅ 100% local - Works offline, no cloud dependencies
  • ✅ No vendor lock-in - Full import/export to JSON

Free Tier:

  • ✅ Up to 100 tasks per project
  • ✅ Full-text search across tasks, conversations, decisions
  • ✅ Complete import/export for portability
  • ✅ Works with any MCP-compatible AI tool

Upgrade for Teams:

  • 🚀 Unlimited tasks and projects
  • 🚀 Multi-agent coordination with task locking
  • 🚀 Real-time collaboration dashboard
  • 🚀 AI code review and analysis

🚀 Quick Start

Installation

Step 1: Configure your AI tool

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "project-brain": {
      "command": "npx",
      "args": ["-y", "@nihalcastelino/project-brain-mcp"]
    }
  }
}

For Cursor, add to config at: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Step 2: Restart your AI tool

That's it! npx will automatically download and run the package on first use.

Optional: Install globally for faster startup

npm install -g @nihalcastelino/project-brain-mcp

Then change config to:

{
  "mcpServers": {
    "project-brain": {
      "command": "project-brain-mcp"
    }
  }
}

Alternative: Install from source

git clone https://github.com/nihalcastelino/project-brain-mcp.git
cd project-brain-mcp
npm install
npm run build

Then use the same config as above, but change the command to point to your local installation.

Usage

Once configured, use these MCP tools in your AI conversations:

# Create a project
pb_create_project(name="My App", description="Building a web app")

# Create a task
pb_create_task(projectId="...", title="Implement auth", priority="high")

# List tasks
pb_list_tasks(projectId="...")

# Complete a task
pb_complete_task(taskId="...")

# Export project to Markdown
pb_export_project(projectId="...", format="markdown")

📖 Features in Detail

🔍 Full-Text Search (NEW!)

  • Search tasks - Find tasks by title, description, or notes
  • Search conversations - Find past discussions instantly
  • Search decisions - Locate architectural choices quickly
  • Project-scoped - Search across all projects or filter by project
  • Fast SQLite search - Up to 50 results per query

Example:

pb_search_conversations({ query: "JWT authentication error" })
// Returns all conversations mentioning JWT auth issues

💾 Import/Export (NEW!)

  • Complete project backup - Export everything as JSON
  • Restore from backup - Import projects with full history
  • No vendor lock-in - Your data is portable
  • Respects limits - Import stops at 100 tasks in free tier

Example:

// Export project
pb_export_project_json({ projectId: "proj-123" })

// Import to new environment
pb_import_project({ data: backupData })

📋 Task Management

  • Create, read, update, delete tasks
  • Set priority (low, medium, high) and due dates
  • Track status (todo, in-progress, done, blocked)
  • Assign to specific AI agents (claude, cursor, copilot)
  • 100 tasks per project (free tier)

🗂️ Project Organization

  • Group related tasks into projects
  • Filter tasks by status, priority, assignee, due date
  • Export entire projects to Markdown/JSON

💬 Conversation Logging

  • Track AI discussions about tasks
  • Log user, assistant, and system messages
  • Attach structured metadata (code snippets, errors, etc.)
  • Searchable history - Find any past conversation

✅ Decision Tracking

  • Record important technical decisions
  • Provide multiple choice options or free-form answers
  • Track who decided and why
  • Link decisions to tasks and conversations

💎 Upgrade to Team Edition

Why Upgrade?

You'll want Team Edition if you:

  • 👥 Work with others using different AI tools (Cursor + Claude + Copilot)

    • Team Edition adds task locking so agents don't conflict
    • Real-time presence - see who's working on what
    • Live collaboration - watch terminal output from team members

  • 🤖 Need AI-powered insights

    • AI code review - Claude Sonnet 4 checks every commit
    • Conversation analysis - Automatic summarization and insights
    • Prompt quality coaching - Improve how you work with AI

  • 🌿 Want advanced Git features

    • Git worktrees - Isolated branches per task automatically
    • Quality gates - Tests must pass before merging
    • Conflict prevention - Never overwrite each other's work

  • 📊 Need project visibility

    • Real-time dashboard - Kanban board with drag & drop
    • Activity feed - See all team actions live
    • Analytics - Track team productivity and AI usage

  • 🚀 Hit the 100 task limit

    • Team Edition has unlimited tasks and projects
    • Import your backups seamlessly

Not just "more tasks" - it's about coordinating multiple agents and humans working together.

Pricing

  • Free Tier: $0/month - 100 tasks/project, single user, local-only
  • Team Edition: $20/user/month (annual) - Unlimited everything + collaboration
  • Trial: 14 days free, no credit card required

Start Free Trial →

🛠️ Development

Clone & Build

git clone https://github.com/nihalcastelino/project-brain-mcp.git
cd project-brain-mcp
npm install
npm run build

Testing Locally

npm run dev

📚 MCP Tools Reference

Projects

  • pb_create_project - Create a new project
  • pb_list_projects - List all projects
  • pb_get_project - Get project details
  • pb_update_project - Update project name/description
  • pb_delete_project - Delete project

Tasks

  • pb_create_task - Create a new task (FREE LIMIT: 100/project)
  • pb_list_tasks - List all tasks (with filters)
  • pb_get_task - Get task details
  • pb_update_task - Update task details
  • pb_complete_task - Mark task as done
  • pb_delete_task - Delete task

Conversations

  • pb_create_conversation - Start a conversation
  • pb_log_message - Log a message (user/assistant/system)
  • pb_get_conversation - Get conversation details
  • pb_get_messages - Get all messages
  • pb_list_conversations - List conversations
  • pb_delete_conversation - Delete conversation

Decisions

  • pb_create_decision - Create a decision point
  • pb_answer_decision - Answer a decision
  • pb_list_decisions - List decisions

🔍 Search (NEW!)

  • pb_search_tasks - Search tasks by keyword (title, description, notes)
  • pb_search_conversations - Search conversations by keyword (title, messages)
  • pb_search_decisions - Search decisions by keyword (question, answer, rationale)

💾 Import/Export

  • pb_export_project - Export project to Markdown/Chat/Plain text
  • pb_export_task - Export task with conversations
  • pb_export_conversation - Export conversation
  • pb_export_project_json - Export complete project backup as JSON (NEW!)
  • pb_import_project - Import project from JSON backup (NEW!)

Utility

  • pb_ping - Test MCP connection

🗄️ Data Storage

Free Tier: All data stored locally in SQLite database at:

  • macOS: ~/.project-brain/project-brain.db
  • Linux: ~/.project-brain/project-brain.db
  • Windows: %USERPROFILE%\.project-brain\project-brain.db

No cloud sync. Your data never leaves your machine.

🤝 Contributing

We welcome contributions! Note:

  • This free tier is 100% open source (MIT license)
  • Team Edition features are in a separate commercial offering

To contribute:

  1. Fork the repo
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Please ensure:

  • Code follows existing style
  • Tests pass (if applicable)
  • README updated (if needed)

📄 License

MIT License - See LICENSE for details

This means you can:

  • ✅ Use commercially
  • ✅ Modify
  • ✅ Distribute
  • ✅ Use privately

🆘 Support

Free Tier (Community Support):

Paid Tier (Priority Support):

🔗 Links

⭐ Star Us!

If you find Project Brain helpful, please star the repo!

It helps others discover the project and motivates us to keep improving it.

Made with ❤️ by the Project Brain team

Helping AI agents collaborate, one task at a time.

Reviews

No reviews yet

Sign in to write a review