Quick Start

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.

Get the GitScrum MCP Server running in under 5 minutes. By the end of this guide, your AI assistant will have full access to your GitScrum workspaces, projects, tasks, sprints, and more.

Prerequisites

Before you begin, make sure you have the following:

If you don't have Node.js installed, download it from nodejs.org. The LTS version is recommended.

Installation

Option 1: Run with npx (recommended)

No installation needed. The MCP server runs directly through npx, which downloads and executes the latest version automatically:

npx -y @gitscrum-studio/mcp-server

This is the recommended approach because:

• Always uses the latest version
• No global packages to maintain
• No manual updates required
• Works immediately across all operating systems

Option 2: Global install

If you prefer a persistent installation:

npm install -g @gitscrum-studio/mcp-server

After global installation, the server binary is available as gitscrum-mcp-server in your PATH. To update later:

npm update -g @gitscrum-studio/mcp-server

Configure Your Client

Choose your AI client and add the GitScrum MCP Server to its configuration.

Claude Desktop

Locate the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json
• Windows: %APPDATA%\Claude\claudedesktopconfig.json

If the file doesn't exist, create it. Add the following configuration:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

If you already have other MCP servers configured, add the "gitscrum" entry inside the existing "mcpServers" object:

{
  "mcpServers": {
    "existing-server": { ... },
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Restart Claude Desktop after saving the configuration file. The GitScrum tools appear in Claude's tool list automatically.

VS Code with GitHub Copilot

Create or edit .vscode/mcp.json in your project root:

{
  "servers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

This configuration applies to the current workspace. For global access across all projects, add it to your VS Code user settings instead.

After saving, GitHub Copilot detects the MCP server automatically. You can verify by opening Copilot Chat and asking about your GitScrum workspace.

Cursor

Open Cursor Settings and navigate to the MCP section, or edit the configuration file directly:

• macOS: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Restart Cursor after saving. The GitScrum tools appear in Cursor's tool listing.

Windsurf

Add the following to your Windsurf MCP configuration:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Continue (VS Code / JetBrains)

Add GitScrum to your Continue configuration file (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "gitscrum",
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  ]
}

Authenticate

The first time you interact with the GitScrum MCP Server, you need to authenticate. The server uses OAuth 2.0 Device Authorization Grant — a secure, browser-based flow.

Step-by-step

1. Tell your AI assistant to log in. Type something like:

`` Login to GitScrum ``

1. The AI assistant calls auth_login and returns a verification URL and a user code. You'll see a message like:

`` Open this URL in your browser: https://gitscrum.com/device Enter code: ABCD-1234 ``

1. Open the URL in your browser and enter the code shown. Sign in to your GitScrum account if prompted, then approve the access request.

1. Tell your AI assistant to complete authentication:

`` Complete the GitScrum login ``

1. The AI calls auth_complete and confirms your session is active. Your authentication token is stored locally at ~/.gitscrum/auth.json.

From this point forward, the MCP server authenticates automatically. Tokens refresh in the background, so you won't need to log in again unless you explicitly sign out or the token expires.

Verifying your session

At any time, ask your AI assistant:

Check my GitScrum auth status

The auth_status tool returns your current session state, including the authenticated user and workspace access.

Your First Commands

Now that you're authenticated, try these commands to explore what the MCP server can do:

Explore your workspace

List my GitScrum workspaces

Returns all workspaces you have access to, with their slugs and details.

View your tasks

Show my tasks for today

Fetches tasks assigned to you that are due or scheduled for today, across all projects.

Get project overview

Show me the projects in my workspace

Lists all projects in your current workspace with stats and team members.

Create a task

Create a task called "Update API documentation" in the Backend project with high priority

Creates a new task with the specified title, project, and priority.

Check sprint progress

How is the current sprint going?

Returns sprint KPIs, progress metrics, and burndown data for the active sprint.

Start a timer

Start tracking time on task PROJ-42

Begins a time tracking session on the specified task.

Get a standup summary

What did the team complete yesterday?

Generates a standup digest with completed work, blockers, and contributor activity.

What's Available

Here's a quick reference of what you can do through the MCP server:

Troubleshooting

"Command not found" or npx fails

Verify Node.js is installed and version 18+:

node --version

If the version is below 18, update Node.js from nodejs.org.

MCP server not appearing in client

• Claude Desktop: Restart the application after editing the config file. Verify JSON syntax is valid.
• VS Code: Ensure the .vscode/mcp.json file is in the workspace root. Reload the window (Ctrl+Shift+P → "Reload Window").
• Cursor: Restart Cursor after editing the config file.

Authentication fails

• Ensure you opened the correct verification URL in a browser where you're signed in to GitScrum.
• Enter the code exactly as shown (including the hyphen).
• Complete the browser flow within 15 minutes — device codes expire.
• If the code expired, run auth_login again to get a new code.

"Unauthorized" errors after authentication

Your token may have expired. Ask your AI assistant:

Log out of GitScrum and log back in

This clears the stored token and initiates a fresh authentication flow.

Rate limiting

If you receive 429 errors, the server is being rate-limited. Wait a few minutes before making additional requests. Rate limits reset automatically.

Next Steps

• Configuration: Advanced setup for all clients, Docker, environment variables, and custom arguments.
• Authentication: Deep dive into the OAuth 2.0 Device Grant flow, token management, and security.
• Security: Enterprise security model, operation restrictions, and best practices.
• MCP Overview: Full tool reference with all 29 tools and 160+ operations.