GitLab Milestone MCP Server

An MCP (Model Context Protocol) server that provides GitLab milestone dates for the gitlab-org group. Inspired by mnohr/milestone-dates.

Tools

get_milestone

Returns the milestone for a given date (defaults to today). Accepts an optional date parameter in YYYY-MM-DD format.

{
  "title": "19.0",
  "start_date": "2026-04-11",
  "due_date": "2026-05-15",
  "release_date": "2026-05-21",
  "quarter": "FY27-Q2",
  "state": "active"
}

list_milestones

Lists milestones with an optional filter parameter:

• "upcoming" (default) — future milestones
• "current" — active milestone only
• "recent" — last 10 completed milestones
• "all" — everything

Each milestone includes: title, start_date, due_date, release_date (3rd Thursday of the month), fiscal quarter, and state.

Setup

Prerequisites

• Node.js 18+
• One of:
  • glab CLI authenticated (glab auth login) — works automatically, no extra config
  • A GitLab personal access token with read_api scope

Build

git clone <repo-url>
cd gitlab-milestone-mcp-server
npm install
npm run build

Add to Claude Code

claude mcp add gitlab-milestones -- node /path/to/gitlab-milestone-mcp-server/dist/index.js

Or with an explicit token:

claude mcp add --env GITLAB_TOKEN=glpat-xxxx gitlab-milestones -- node /path/to/gitlab-milestone-mcp-server/dist/index.js

Add to GitLab Duo CLI

Add the following to ~/.gitlab/duo/mcp.json:

{
  "mcpServers": {
    "gitlab-milestones": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/gitlab-milestone-mcp-server/dist/index.js"],
      "approvedTools": ["get_milestone", "list_milestones"]
    }
  }
}

If you need to pass a token explicitly:

{
  "mcpServers": {
    "gitlab-milestones": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/gitlab-milestone-mcp-server/dist/index.js"],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxx"
      },
      "approvedTools": ["get_milestone", "list_milestones"]
    }
  }
}

Authentication

The server resolves credentials in this order:

1. GITLAB_TOKEN environment variable (uses PRIVATE-TOKEN header for PATs)
2. glab CLI token (uses Authorization: Bearer header for OAuth tokens)
3. Error with instructions if neither is available

Cache

Milestones are cached to ~/.cache/gitlab-milestone-mcp-server/milestones.json and persist across server restarts. The cache refreshes when:

• No cache file exists
• No future milestones remain in the cache
• The cache is older than 7 days

Configuration

| Environment Variable | Default | Description | |---|---|---| | GITLAB_TOKEN | — | GitLab personal access token (optional if glab is configured) | | GITLAB_GROUP_ID | 9970 | GitLab group ID to fetch milestones from |

License

MIT