collab-mcp-server

erkandogan/collab-mcp-server

3.2

If you are the rightful owner of collab-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Collab MCP Server is a robust Model Context Protocol server designed to facilitate seamless interaction between AI assistants and Collab's unified Issue system, projects, views, and workspaces using OAuth authentication.

Tools
5
Resources
0
Prompts
0

Collab MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants to interact with Collab's unified Issue system, projects, views, and workspaces through OAuth authentication.

Features

  • 🔐 OAuth 2.0 Authentication - Secure integration with Collab's existing app infrastructure
  • 📝 Issue Management - Create, update, delete, and manage all issue types (Task, Bug, Epic, Story, Milestone, Subtask)
  • 🏗️ Project Operations - Full project lifecycle management
  • 👀 Custom Views - Create and manage filtered views with Kanban, List, Table, Calendar, Timeline, and Gantt displays
  • 🔍 Powerful Search - Full-text search across issues, projects, and users
  • 🏷️ Labels & Relations - Organize and link issues
  • 📊 Rich Resources - Access workspace overviews, project stats, issue details, and activity logs
  • 🎯 Guided Prompts - Pre-built workflows for bug reports, feature requests, triaging, and more

Installation

Prerequisites

  • Node.js >= 18.0.0
  • PostgreSQL database (same as main Collab app)
  • Access to Collab workspace

Setup

  1. Install dependencies:

    cd mcp-server
npm install

  2. Configure environment:

    cp .env.example .env
# Edit .env with your database URL and settings

  3. Build the server:

    npm run build

Usage

Running the MCP Server (Stdio)

Development mode (with hot reload):

npm run dev

Production mode:

npm start

Running the Web Server (Manifest Hosting)

For App Store submission, run the web server to host the manifest:

Development mode:

npm run dev:web

Production mode:

npm run start:web

Run both servers:

npm run serve:both

The web server provides:

  • App manifest at /manifest
  • OAuth callback at /oauth/callback
  • Webhook endpoint at /webhooks/events
  • Health check at /health

Connecting from Cursor IDE

Add to your Cursor MCP settings (.cursor/mcp.json or global settings):

{
  "mcpServers": {
    "collab": {
      "command": "node",
      "args": ["/path/to/collab/mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/collab",
        "ACCESS_TOKEN": "your-oauth-access-token"
      }
    }
  }
}

Authentication

The MCP server uses OAuth 2.0 tokens from Collab's App Store:

  1. Register your MCP client as an app in Collab (/dev/apps/new)
  2. Generate OAuth credentials (client_id, client_secret)
  3. Complete OAuth flow to get access token
  4. Include token in MCP requests via ACCESS_TOKEN environment variable

Available Tools

Issue Management

  • create_issue - Create new issues (any type)
  • update_issue - Update issue properties
  • delete_issue - Delete issues
  • add_issue_comment - Add comments with threading
  • update_issue_status - Change issue status
  • assign_issue - Assign or reassign issues

Project Management

  • create_project - Create new projects with default statuses
  • update_project - Update project properties
  • archive_project - Archive/unarchive projects

View Management

  • create_view - Create custom filtered views
  • update_view - Update view configuration
  • delete_view - Remove views

Organization

  • create_label - Create workspace labels
  • add_label_to_issue - Tag issues
  • remove_label_from_issue - Untag issues
  • create_issue_relation - Link issues with relationships
  • remove_issue_relation - Remove issue links

See for detailed tool documentation.

Available Resources

Workspace Resources

  • workspace://{workspaceId}/overview - Workspace stats and activity
  • workspace://{workspaceId}/projects - All projects
  • workspace://{workspaceId}/members - Team members
  • workspace://{workspaceId}/views - Available views

Project Resources

  • project://{projectId}/issues - Filtered project issues
  • project://{projectId}/statuses - Project status workflow
  • project://{projectId}/activity - Recent activity
  • project://{projectId}/stats - Project metrics

Issue Resources

  • issue://{issueIdOrKey} - Full issue details (supports "MA-123" format)
  • issue://{issueIdOrKey}/comments - Comment tree with reactions
  • issue://{issueIdOrKey}/activity - Change history
  • issue://{issueIdOrKey}/relations - Related issues

View Resources

  • view://{viewId}/issues - Issues filtered by view
  • view://{viewId}/config - View configuration

Search Resources

  • search://issues?q={query} - Full-text issue search
  • search://projects?q={query} - Project search
  • search://users?q={query} - User search (workspace-scoped)

See for detailed resource documentation.

Available Prompts

Creation Workflows

  • create-bug-report - Guided bug report creation
  • create-feature-request - Feature request template
  • create-epic-with-stories - Epic breakdown wizard

Management Workflows

  • triage-issues - Bulk issue triage
  • sprint-planning - Sprint planning assistant
  • standup-summary - Daily standup generator

Analysis Workflows

  • project-health-check - Project metrics & bottlenecks
  • user-workload - Team capacity analysis
  • velocity-report - Sprint velocity tracking

Examples

See for practical usage examples including:

  • Creating issues from natural language
  • Bulk operations with filters
  • Custom view creation
  • Sprint planning workflows
  • Automated reporting

App Store Submission

To submit the MCP Server to Collab's App Store marketplace:

  1. Prepare manifest and icon (already done!)
  2. Start web server: npm run dev:web
  3. Make publicly accessible (deploy or use ngrok)
  4. Submit: Navigate to https://collab.weez.boo/dev/apps/submit
  5. Provide manifest URL: https://collab.weez.boo/mcp-server/manifest

See for detailed submission guide.

Development

Project Structure

mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types/                # TypeScript type definitions
│   ├── utils/                # Utilities (prisma, logger, errors)
│   ├── auth/                 # OAuth & permissions
│   ├── tools/                # MCP tools (write operations)
│   ├── resources/            # MCP resources (read operations)
│   ├── prompts/              # Guided workflows
│   └── schemas/              # Zod validation schemas
├── package.json
├── tsconfig.json
└── README.md

Adding New Tools

  1. Define Zod schema in src/schemas/
  2. Implement tool logic in src/tools/
  3. Register tool in src/index.ts
  4. Add tests and documentation

Adding New Resources

  1. Implement resource handler in src/resources/
  2. Register resource URI pattern in src/index.ts
  3. Add documentation and examples

Security

  • All operations are OAuth-authenticated
  • Workspace-scoped access control
  • Permission checks on every operation
  • Rate limiting per installation
  • Audit logging for compliance

Troubleshooting

"Authentication failed"

  • Verify your OAuth access token is valid
  • Check token hasn't expired
  • Ensure app installation is ACTIVE

"Access denied"

  • Verify you have access to the workspace
  • Check workspace membership status
  • Ensure operation is within installation scope

"Database connection failed"

  • Verify DATABASE_URL is correct
  • Check PostgreSQL is running
  • Ensure database exists

See for more help.

Contributing

Contributions are welcome! Please see for guidelines.

License

MIT License - see for details.

Support

Built with ❤️ by the Collab team