Date Operations MCP Server

A Model Context Protocol (MCP) server providing reliable date calculations with UK context, specifically designed for James Murrell's BA workflow.

Features

• Working Day Calculations: Automatically excludes weekends and UK bank holidays

• UK Bank Holiday Integration: Fetches live data from GOV.UK API

• Asana-Specific Helpers: Follows James's rules (next working day at 4 PM, Friday → Monday)

• Sprint Planning Tools: Calculate sprint dates and current sprint information

• UK Timezone: All dates handled in Europe/London timezone (GMT/BST)

Installation

# Clone or create the project directory
mkdir date-operations-mcp
cd date-operations-mcp

# Copy all the artifact files into the project:
# - package.json
# - tsconfig.json
# - src/index.ts
# - src/dateCalculations.ts
# - src/bankHolidays.ts
# - src/asanaHelpers.ts

# Install dependencies
npm install

# Build the project
npm run build

Configuration for Claude Desktop

Add this to your Claude Desktop config file:

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

{
  "mcpServers": {
    "date-operations": {
      "command": "node",
      "args": ["/absolute/path/to/date-operations-mcp/build/index.js"]
    }
  }
}

Replace /absolute/path/to/date-operations-mcp with your actual project path.

Restart Claude Desktop

After updating the config file, restart Claude Desktop completely for the MCP server to load.

Available Tools

Basic Date Operations

get_today_uk

• Get current date in UK timezone

• No parameters required

get_next_working_day

• Get next working day after a given date

• Parameters: from_date (ISO format or "today")

calculate_working_days

• Add or subtract working days from a date

• Parameters: start_date, num_days, direction (forward/backward)

get_working_days_between

• Count working days between two dates

• Parameters: start_date, end_date

UK Bank Holidays

is_uk_bank_holiday

• Check if a date is a UK bank holiday

• Parameters: date

get_upcoming_bank_holidays

• Get list of upcoming UK bank holidays

• Parameters: months_ahead (optional, default: 6)

Sprint Planning

calculate_sprint_dates

• Calculate sprint start and end dates

• Parameters: start_date, sprint_length_weeks

get_current_sprint_info

• Get current sprint number and remaining days

• Parameters: first_sprint_start, sprint_length_weeks

Asana Helpers

get_asana_due_date

• Get Asana due date following James's rules

• Parameters: from_date (optional, defaults to today)

• Returns next working day at 4:00 PM (Friday → Monday)

parse_asana_date_request

• Parse natural language requests

• Parameters: request (e.g., "tomorrow", "in 5 days", "in 2 weeks")

• Returns appropriate Asana due date

Example Usage

Once configured, Claude will automatically use these tools when you ask date-related questions:

You: "What's 5 working days from today?"
Claude: [Uses calculate_working_days tool] That's Wednesday, October 29, 2025

You: "Create an Asana reminder for next week"
Claude: [Uses parse_asana_date_request tool] Setting due date to Monday, October 27, 2025 at 4:00 PM

You: "When do we finish the current sprint?"
Claude: [Uses get_current_sprint_info tool] Current sprint ends Friday, October 31, 2025

Technical Details

• Language: TypeScript

• Runtime: Node.js

• Date Library: date-fns with timezone support

• UK Holidays: GOV.UK official API (cached for 24 hours)

• Timezone: Europe/London (handles GMT/BST automatically)

Troubleshooting

Server not showing up in Claude:

1. Check the absolute path in your config file

2. Ensure npm run build completed successfully

3. Restart Claude Desktop completely

4. Check Claude Desktop logs for errors

Date calculations seem wrong:

1. Verify UK bank holiday API is accessible

2. Check your system timezone settings

3. Use get_today_uk tool to verify current date

Testing

You can test the server before integrating with Claude:

# Run the built server directly
node build/index.js

# It should output: "Date Operations MCP Server running on stdio"

Notes

• Bank holiday data is cached for 24 hours to reduce API calls

• All dates use UK timezone (Europe/London) with automatic GMT/BST handling

• Friday tasks automatically roll to Monday per James's Asana rules

• Working days exclude weekends AND UK bank holidays

📚 Want to Build Tools Like This?

This tool was built using the process documented in "The Business Analyst's Guide to AI-Assisted Tool Development".

Learn how to:

• Identify workflows worth automating

• Work effectively with AI as a collaborator

• Build production-ready tools without being a developer

• Avoid common pitfalls and mistakes

£5 • Real code • Real examples • Real process

Get the guide: https://murrelljames.gumroad.com/l/pvfww

Repository: https://github.com/cs97jjm3/ba-ai-tools-guide