Projects

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The project tool provides 11 actions covering project lifecycle management and metadata access. Beyond creating and listing projects, this tool is the gateway to project configuration — workflows, task types, effort levels, labels, and team members. These metadata endpoints are essential because they provide the IDs and names that other tools (especially task) require for creating and updating items.

Understanding the project tool's metadata actions is key to effective MCP usage. When you ask your AI assistant to create a task with "high priority" assigned to "@sarah" in the "In Progress" column, the assistant first queries project action=efforts, project action=members, and project action=workflows to resolve those human-readable names into the numeric IDs the API expects. The MCP server handles this resolution automatically in most cases, but knowing the metadata actions helps you understand how the system works.

Actions Overview

Creating Projects

The create action sets up a new project within a workspace. The project is immediately available for task creation, sprint planning, and team collaboration.

Required Parameters

Optional Parameters

Example Prompts

You:  "Create a new project called 'Mobile App' in my workspace"
AI:   Calls project action=create with name="Mobile App", company_slug

You:  "Create a private project 'Security Audit' linked to Acme Corp"
AI:   Calls project action=create with name, visibility="private", client_uuid

You:  "Set up a new project 'API v3' with description 'REST API redesign for Q1'"
AI:   Calls project action=create with name, description

Finding and Listing Projects

List

The list action returns all projects within a workspace. You can optionally filter by status. Each project in the response includes its project_slug, which is needed for all project-specific operations.

You:  "List all projects in my workspace"
AI:   Calls project action=list → returns projects with slugs and stats

You:  "Show active projects only"
AI:   Calls project action=list with status="in_progress"

You:  "Which projects are archived?"
AI:   Calls project action=list with status="archived"

Find

The find action searches for a project by name across your workspaces. This is useful when you know the project name but not the slug or workspace. The company_slug parameter is optional — if omitted, the search covers all accessible workspaces.

You:  "Find the Backend project"
AI:   Calls project action=find with name="Backend" → returns project with slug and workspace

You:  "Which workspace has the Mobile App project?"
AI:   Calls project action=find with name="Mobile App" → returns workspace info

Project Details and Statistics

Get

The get action returns the complete project object — name, description, settings, dates, team size, and links. This provides the full context about a project.

You:  "Show me the Backend project details"
AI:   Calls project action=get → returns full project configuration and metadata

Stats

The stats action returns project-level statistics — total tasks, completion rates, active sprints, team activity, and more. These numbers power the project dashboard in the GitScrum web application.

You:  "Show project statistics for the Mobile App"
AI:   Calls project action=stats → returns task counts, completion rates, sprint data

You:  "Which project has the most open tasks?"
AI:   Lists projects → calls stats for each → compares open task counts

Tasks

The tasks action returns all tasks within a project. While the task tool's filter action provides more granular filtering, the project tasks action is a quick way to get an overview of all work items.

You:  "Show all tasks in the Backend project"
AI:   Calls project action=tasks → returns complete task list

Project Metadata

Metadata actions are the bridge between human-readable names and the numeric IDs that the GitScrum API requires. When your AI assistant creates or updates tasks, it relies on these endpoints to translate your natural language into precise API calls.

Workflows (Kanban Columns)

The workflows action returns the project's Kanban board columns with their IDs and titles. Each workflow entry represents a column on the board — "To Do", "In Progress", "Code Review", "Done", etc.

Why it matters: When you say "move this task to In Progress", the AI assistant needs the workflow_id for the "In Progress" column. The MCP server handles this resolution automatically when you use the column parameter on the task tool, but understanding workflows helps you configure boards and troubleshoot column issues.

You:  "What are the available columns in the Backend project?"
AI:   Calls project action=workflows → returns column list:
      [{ id: 1, title: "Backlog" }, { id: 2, title: "In Progress" }, { id: 3, title: "Done" }]

You:  "What workflow stages does the Mobile App project use?"
AI:   Calls project action=workflows → returns the project's Kanban configuration

Types (Task Types)

The types action returns available task types — Feature, Bug, Improvement, Chore, etc. Each type has an id and title.

Why it matters: When you say "create a bug", the AI assistant needs the typeid for the "Bug" type. The MCP server uses this to set the typeid field on the task.

You:  "What task types are available in this project?"
AI:   Calls project action=types → returns type list:
      [{ id: 1, title: "Feature" }, { id: 2, title: "Bug" }, { id: 3, title: "Improvement" }]

Efforts (Priority Levels)

The efforts action returns available effort or priority levels — Low, Medium, High, Critical, etc. Each effort has an id and title.

Why it matters: When you say "create a high-priority task", the AI assistant needs the effortid for the "High" level. The MCP server uses this to set the effortid field on the task.

You:  "What priority levels are available?"
AI:   Calls project action=efforts → returns effort list:
      [{ id: 1, title: "Low" }, { id: 2, title: "Medium" }, { id: 3, title: "High" }]

Labels

The labels action returns all labels configured for the project, each with an id and title. Labels are used for categorization and filtering across tasks.

Why it matters: When you say "label this task as 'frontend' and 'urgent'", the AI assistant needs the label_ids for those labels. The task tool's filter action also resolves label names automatically, but knowing available labels helps you organize work effectively.

You:  "What labels are available in this project?"
AI:   Calls project action=labels → returns label list:
      [{ id: 1, title: "frontend" }, { id: 2, title: "backend" }, { id: 3, title: "urgent" }]

Members

The members action returns all team members assigned to the project, including their display name, username, avatar URL, and role. Usernames are used for task assignment.

Why it matters: When you say "assign this to @sarah", the AI assistant needs to verify that "sarah" is a valid username in the project's member list. The usernames parameter on the task tool accepts these values directly.

You:  "Who are the team members in this project?"
AI:   Calls project action=members → returns member list:
      [{ name: "Sarah Chen", username: "sarah", role: "developer" }, ...]

You:  "Who can I assign tasks to in the Backend project?"
AI:   Calls project action=members → lists assignable team members

Metadata Resolution Flow

Here's how the AI assistant uses metadata to create a fully-configured task:

You:  "Create a high-priority bug 'Login timeout' assigned to @sarah
       in the In Progress column of the Backend project"

AI internally:
  1. project action=efforts   → finds "High" → effort_id=3
  2. project action=workflows → finds "In Progress" → workflow_id=2
  3. project action=members   → validates "sarah" exists
  4. task action=create       → passes title, effort_id=3, column="In Progress",
                                 usernames=["sarah"], is_bug=true

In practice, the MCP server handles much of this resolution automatically. When you pass column: "In Progress" to the task tool, it fetches workflows internally and resolves the ID. But understanding this flow helps when debugging or when the AI assistant asks clarifying questions about available options.

Project Setup Workflow

When setting up a new project through MCP, follow this sequence:

1. Create the project

You:  "Create a project called 'Mobile App' with description 'iOS and Android client'"
AI:   Calls project action=create → returns project_slug

2. Review default configuration

New projects come with default workflows, types, and efforts. Check what's available.

You:  "Show me the workflows, types, and effort levels for Mobile App"
AI:   Calls workflows, types, efforts → displays the project's configuration

3. Start creating tasks

Use the metadata from step 2 to create well-configured tasks.

You:  "Create a task 'Design home screen' as a Feature, medium priority, assign to @alex"
AI:   Uses cached metadata → creates task with correct IDs

4. Monitor progress

Track project health through statistics.

You:  "How is the Mobile App project going?"
AI:   Calls project action=stats → summarizes task completion, active sprints, team activity

Context Auto-Resolution

The project tool supports automatic context resolution. If your AI assistant knows the projectslug but not the companyslug, it attempts to resolve the workspace automatically by searching across your accessible workspaces. This means you can often reference projects by name rather than providing both slugs explicitly.

The find action is particularly helpful here — it searches by project name and returns both the projectslug and companyslug, establishing context for all subsequent operations in the conversation.

Visibility and Permissions

Project visibility determines who can access the project within a workspace:

• Public — All workspace members can see the project and its tasks. This is the default.
• Private — Only explicitly invited members can access the project. Private projects don't appear in workspace-wide task listings for non-members.

The MCP server respects these visibility rules. If you don't have access to a private project, it won't appear in list results and direct get calls will fail with a permission error.

Next Steps

• Tasks: Create and manage tasks within your projects.
• Sprints: Plan and track sprints for iterative delivery.
• Time Tracking: Track time across project tasks.
• Quick Start: Set up the MCP server if you haven't already.