GitHub Calendar MCP Server

How to use

This MCP server is designed to be consumed by MCP clients such as Goose. It exposes tools to retrieve calendar events from GitHub projects, view team status, analyze workloads, and suggest the best assignee for new work. Connect your MCP client to the server using the configuration example provided below, then invoke the available tools to get timely scheduling and staffing information.

To integrate with Goose, use the following MCP server configuration snippet. This starts a local node process that runs the server and passes the required GitHub token through the environment.

{
  "mcpServers": {
    "github_calendar": {
      "command": "node",
      "args": ["/full/path/to/github-calendar-mcp-server/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

How to install

Prerequisites: ensure you have Node.js installed (recommended: Node.js 16+). Preferably use a recent LTS release to avoid compatibility issues.

Step-by-step setup locally (commands shown one per line):

# Create project directory
mkdir github-calendar-mcp-server
cd github-calendar-mcp-server

# Install dependencies
npm install

# Run the server (development/start command as per README)
npm start

Configuration

The server ships with predefined defaults and exposes a configurable surface for organization, project, label filtering, and date ranges. The defaults are stated below, and you can modify them in the source file as needed.

Default configuration values described in the README include the following:

const DEFAULT_ORG = 'your-org';
const DEFAULT_PROJECT_NUMBER = 123;
const DEFAULT_LABEL = 'your-label';

Data sources

The server aggregates data from multiple GitHub sources to provide calendar events and schedules. Primary data comes from the GitHub Projects v2 API (GraphQL). If needed, it falls back to the GitHub Search API. It also uses issue custom fields for start/end dates, parses issue bodies for dates, and considers milestone due dates to enrich scheduling information.

Error handling

The server includes robust error handling for common failure modes. Authentication errors surface clear messages about token issues; API rate limits are managed gracefully; fallen-back requests switch between GraphQL and REST as needed; and missing data results in sane defaults to keep the MCP experience smooth.

Troubleshooting

Common issues include authentication failures, project access problems, or no events found within the configured date range. Verify your GITHUB_TOKEN permissions, ensure the organization and project are accessible, and check that the date range and filters align with existing data.

Development

To extend the server, you can add new tools, extend data sources via the GitHub API, integrate with UI components, and implement caching for better performance.

Notes

This MCP server is tailored for GitHub project calendars and team workloads, enabling AI assistants to schedule and optimize work across GitHub organizations and teams.