@nihalcastelino/project-brain-mcp

v2.0.0

Published

12 days ago

Multi-agent AI orchestration platform with 50+ MCP tools

0High
0Medium
0Low

nihal1983

mcp ai task-management claude cursor copilot project-management offline local-first

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.

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

One-Command Installation

That's it! Setup is completely automated:

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

This will:

✅ Install dependencies
✅ Build the MCP server
✅ Auto-detect Claude Desktop and Cursor
✅ Configure them automatically
✅ Create local database

Restart your AI tool and you're ready to go!

Alternative: Install from source

git clone https://github.com/nihalcastelino/project-brain-mcp.git
cd project-brain-mcp
npm install  # Automatically builds and configures

Manual Configuration (if auto-setup fails)

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

{
  "mcpServers": {
    "project-brain": {
      "command": "node",
      "args": ["/path/to/project-brain-mcp/dist/server.js"],
      "env": {
        "PROJECT_BRAIN_DB_PATH": "~/.project-brain/tasks.db"
      }
    }
  }
}

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

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:

Fork the repo
Create a feature branch
Make your changes
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):

GitHub Issues: github.com/nihalcastelino/project-brain-mcp/issues
Discussions: github.com/nihalcastelino/project-brain-mcp/discussions

Paid Tier (Priority Support):

Email: [email protected]
Response time: < 24 hours
Dedicated Slack channel

🔗 Links

Website: project-brain.io
Documentation: docs.project-brain.io
Team Edition: project-brain.io/upgrade
GitHub: github.com/nihalcastelino/project-brain-mcp

⭐ 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.