com.gitscrum/mcp

Install

Config snippet generator goes here (5 client tabs)

README

<p align="center">
  <img src="https://site-assets.gitscrum.com/vscode/gitscrum-white.png" alt="GitScrum" width="160"/>
</p>

<h1 align="center">GitScrum MCP Server: Your AI Agent as a Project Manager 🚀</h1>
<p align="center">
  <a href="https://www.npmjs.com/package/@gitscrum-studio/mcp-server"><img src="https://img.shields.io/npm/v/@gitscrum-studio/mcp-server?style=flat-square&color=000" alt="npm version"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-000?style=flat-square" alt="MIT License"></a>
  <a href="https://github.com/gitscrum-core/mcp-server/actions"><img src="https://img.shields.io/badge/tests-378_passing-000?style=flat-square" alt="Tests"></a>
</p>

<p align="center">
  Turn your AI Agent into a full-scale Project Manager.<br/>
 The Official Model Context Protocol (MCP) server for GitScrum provides AI assistants (Claude, Cursor, Windsurf, Copilot) with deep context and operational access to your entire project stack.

</p>

<div align="center">
    <img src="https://github.com/user-attachments/assets/adbcac95-f1cb-4ad3-852c-24120bc13de6" alt="GitScrum MCP Server">
</div>


<br/>

<table>
<tr>
<td width="50%">

### ⚡ Hosted (Recommended)

**Zero install. Works everywhere.**

```
https://mcp.gitscrum.com/sse
```

SSE-based server hosted on AWS. Just add URL + token to your AI client.

**Best for:** Claude Desktop, Cursor, Windsurf, any SSE-compatible client.

[→ Setup Guide](docs/HOSTED.md)

</td>
<td width="50%">

### 📦 Local (npm)

**Self-hosted via npx.**

```bash
npx -y @gitscrum-studio/mcp-server
```

Runs locally via stdio transport. Requires Node.js 18+.

**Best for:** VS Code, GitHub Copilot, offline environments.

[→ Local Setup](#quick-start)

</td>
</tr>
</table>

---

## Overview

GitScrum Studio MCP Server connects AI assistants to your [GitScrum](https://gitscrum.com) workspace via the [Model Context Protocol](https://modelcontextprotocol.io). It gives Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack — tasks, sprints, time tracking, user stories, epics, kanban workflows, team discussions, wiki, notes, client CRM, invoicing, proposals, budget tracking, analytics dashboards, standup reports, and activity feeds.

Everything your team does in the GitScrum web app, your AI assistant can now do through conversation.

```
You:    "What's on my plate today?"
Assistant: Fetches your tasks due today across all projects.

You:    "Create a sprint for next week with the top 5 backlog items"
Assistant: Creates the sprint, assigns tasks, and sets the timeline.

You:    "Show me which projects are over budget"
Assistant: Returns burn-down data and flags at-risk projects.

You:    "Send the Q1 proposal to Acme Corp"
Assistant: Creates the proposal, attaches the client, and sends it.

You:    "What did the team ship this week?"
Assistant: Generates a standup digest with completed work and blockers.
```

**29 tools. 160+ operations. Zero context switching.**

---

## Quick start

### Install

```bash
npx -y @gitscrum-studio/mcp-server
```

### Configure your client

<details>
<summary><strong>Claude Desktop</strong></summary>

Edit the configuration file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}
```
</details>

<details>
<summary><strong>VS Code / Cursor</strong></summary>

Add to `.vscode/mcp.json` or your MCP settings:

```json
{
  "servers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}
```
</details>

### Authenticate

Tell your AI assistant: **"Login to GitScrum"**

The server initiates an [OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) flow. You authorize in the browser — credentials are never shared with the MCP server.

---

## Tools

Each tool uses a consolidated `action` parameter, reducing LLM context tokens by ~80% compared to individual tool definitions.

### Core

| Tool | Actions | Docs |
|:-----|:--------|:-----|
| `task` | `my` `today` `get` `create` `update` `complete` `subtasks` `filter` `by_code` `duplicate` `move` `notifications` | [tasks](docs/tools/tasks.md) |
| `sprint` | `list` `all` `get` `kpis` `create` `update` `stats` `reports` `progress` `metrics` | [sprints](docs/tools/sprints.md) |
| `workspace` | `list` `get` | [projects](docs/tools/projects.md) |
| `project` | `list` `get` `stats` `tasks` `workflows` `types` `efforts` `labels` `members` | [projects](docs/tools/projects.md) |
| `time` | `active` `start` `stop` `logs` `analytics` `team` `reports` `productivity` `timeline` | [time-tracking](docs/tools/time-tracking.md) |

### Planning

| Tool | Actions | Docs |
|:-----|:--------|:-----|
| `user_story` | `list` `get