Configuration

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.

This guide covers detailed configuration for every supported MCP client, environment variables, Docker usage, custom arguments, and verification steps. If you followed the Quick Start and need more advanced setup options, this is your reference.

Claude Desktop

Claude Desktop reads its MCP configuration from a JSON file on your local filesystem.

Configuration file location

If the file doesn't exist, create it manually. Ensure the parent directories exist.

Minimal configuration

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

This tells Claude Desktop to start the GitScrum MCP Server using npx, which downloads and runs the latest version automatically.

Adding to existing configuration

If you already have other MCP servers configured, add gitscrum as a new entry in the mcpServers object:

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

Using a global installation

If you installed the server globally with npm install -g @gitscrum-studio/mcp-server, reference the binary directly:

{
  "mcpServers": {
    "gitscrum": {
      "command": "gitscrum-mcp-server"
    }
  }
}

With environment variables

To pass environment variables to the MCP server process:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"],
      "env": {
        "GITSCRUM_API_URL": "https://services.gitscrum.com"
      }
    }
  }
}

Applying changes

Restart Claude Desktop after editing the configuration file. Claude Desktop reads the config only at startup. After restarting, the GitScrum tools appear automatically in Claude's tool listing.

VS Code with GitHub Copilot

GitHub Copilot reads MCP server configurations from a JSON file in your workspace or user settings.

Workspace configuration (per-project)

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

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

This configuration applies only to the current workspace. Team members who open the same project will also get the GitScrum MCP Server configured automatically if the file is committed to version control.

User-level configuration (global)

To make the GitScrum MCP Server available in all VS Code workspaces, add it to your VS Code user settings. Open settings (Ctrl+, / Cmd+,), search for "mcp", and add the server configuration. Alternatively, edit settings.json:

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

Verification

After saving the configuration:

1. Open the GitHub Copilot Chat panel
2. Type: "List my GitScrum workspaces"
3. Copilot should invoke the MCP server and return your workspace data

If the tools don't appear, reload the window: Ctrl+Shift+P → "Developer: Reload Window".

Cursor

Cursor supports MCP servers through its configuration system.

Configuration file location

Configuration

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

Via Cursor Settings UI

Alternatively, navigate to Cursor Settings → MCP and add a new server:

• Name: gitscrum
• Command: npx
• Arguments: -y @gitscrum-studio/mcp-server

Applying changes

Restart Cursor after editing the configuration. The GitScrum tools appear in the tool listing in Cursor's AI panel.

Windsurf

Windsurf reads MCP configuration from its settings file.

Configuration

Add to your Windsurf MCP configuration:

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

Restart Windsurf after saving to activate the server.

Continue (VS Code / JetBrains)

Continue supports MCP servers through its configuration file.

Configuration file

Edit ~/.continue/config.json and add the GitScrum server to the mcpServers array:

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

If you already have other MCP servers in the array, append the GitScrum entry:

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

Environment Variables

The GitScrum MCP Server recognizes the following environment variables:

Setting environment variables

In client configuration (recommended for per-server settings):

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"],
      "env": {
        "GITSCRUM_TOKEN": "your-token-here"
      }
    }
  }
}

Shell-level (applies to all processes):

# macOS/Linux
export GITSCRUM_TOKEN=your-token-here

# Windows PowerShell
$env:GITSCRUM_TOKEN = "your-token-here"

# Windows CMD
set GITSCRUM_TOKEN=your-token-here

Important: GITSCRUM_TOKEN bypasses the secure OAuth flow. Only use it in CI/CD pipelines or automated environments where browser-based authentication isn't practical. For interactive use, always use the OAuth Device Grant flow.

Using with Docker

If you run development environments in Docker containers, you can include the MCP server in your Docker setup.

Dockerfile

FROM node:18-alpine

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

ENTRYPOINT ["gitscrum-mcp-server"]

Docker Compose with volume mount

To persist authentication across container restarts, mount the token directory:

services:
  mcp:
    image: node:18-alpine
    command: npx -y @gitscrum-studio/mcp-server
    volumes:
      - ~/.gitscrum:/root/.gitscrum

Docker with environment variable

For containerized environments, pass the token directly:

services:
  mcp:
    image: node:18-alpine
    command: npx -y @gitscrum-studio/mcp-server
    environment:
      - GITSCRUM_TOKEN=${GITSCRUM_TOKEN}

Note: When running in Docker, the OAuth Device Grant flow may not work as expected since the MCP server runs inside the container but the browser is on the host. Use GITSCRUM_TOKEN for Docker environments.

Custom Server Arguments

The MCP server accepts the following command-line arguments:

Checking the installed version

npx -y @gitscrum-studio/mcp-server --version

Verifying the Connection

After configuring your client, verify that the MCP server is working correctly.

Step 1: Check the server starts

Ask your AI assistant:

Check GitScrum auth status

If the server is running, you'll get a response about your authentication state (either "authenticated" or "not authenticated").

Step 2: Authenticate

If not authenticated, log in:

Log in to GitScrum

Complete the browser-based OAuth flow as described in Authentication.

Step 3: Test a read operation

After authenticating, test with a simple read:

List my GitScrum workspaces

You should see your workspace names. This confirms:

• The MCP server is running
• Authentication is working
• The API connection is valid
• Your account has workspace access

Step 4: Test a write operation

Create a test task to verify write access:

Create a task called "MCP server test" in [your project name]

If the task is created successfully, your MCP server is fully operational.

Updating the MCP Server

With npx (automatic)

If you use npx -y @gitscrum-studio/mcp-server in your configuration, updates are automatic. Each time the MCP server starts, npx checks for the latest version and downloads it if a newer version is available.

To force an update to the latest version:

npx -y @gitscrum-studio/mcp-server@latest --version

With global installation

If you installed globally, update manually:

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

Check your current version:

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

Version pinning

To pin to a specific version (useful for teams that need consistent behavior):

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

Replace 1.2.3 with the desired version number. This prevents automatic updates and ensures all team members use the same version.

Configuration Summary

Quick reference for all supported clients:

All clients use the same MCP server command:

npx -y @gitscrum-studio/mcp-server

Troubleshooting Configuration

JSON syntax errors

Configuration files must contain valid JSON. Common mistakes:

• Trailing commas after the last property in an object
• Missing quotes around keys or string values
• Single quotes instead of double quotes

Use a JSON validator or your editor's JSON language mode to catch syntax errors before saving.

npx caching issues

If npx doesn't pick up a new version:

# Clear the npx cache
npx clear-npx-cache

# Or specify latest explicitly
npx -y @gitscrum-studio/mcp-server@latest

Permission errors on token file

If the MCP server can't read or write ~/.gitscrum/auth.json:

# macOS/Linux: Fix permissions
mkdir -p ~/.gitscrum
chmod 700 ~/.gitscrum
chmod 600 ~/.gitscrum/auth.json

# Windows PowerShell: Verify you own the file
Get-Acl "$env:USERPROFILE\.gitscrum\auth.json" | Format-List

Node.js not found

If the client reports that npx or node is not found, ensure Node.js is in your system PATH. Some clients (especially desktop applications) may not inherit your shell's PATH. You can provide the full path to npx:

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

On Windows, use the full path:

{
  "mcpServers": {
    "gitscrum": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Using MCP Inspector for debugging

The MCP Inspector tool lets you interact with the MCP server directly, bypassing the AI client:

npx @modelcontextprotocol/inspector node dist/index.js

This opens a browser-based inspector where you can call individual tools and see raw responses. Useful for verifying the server works independently of your AI client configuration.

Next Steps

• Quick Start: Fast-track installation and first commands.
• Authentication: Deep dive into the OAuth 2.0 Device Grant flow.
• Security: Enterprise security model and best practices.
• MCP Overview: Full tool reference with all 29 tools and 160+ operations.