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:
- Check the absolute path in your config file
- Ensure
npm run buildcompleted successfully - Restart Claude Desktop completely
- Check Claude Desktop logs for errors
Date calculations seem wrong:
- Verify UK bank holiday API is accessible
- Check your system timezone settings
- Use
get_today_uktool 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