Chronos MCP Server

A time-related server implementing the Model Context Protocol (MCP). This server provides timezone-aware date and time information through a simple MCP interface.

Overview

The Chronos MCP server is built with .NET Core using the Model Context Protocol C# SDK (github.com/modelcontextprotocol/csharp-sdk). It provides tools for accessing date and time information in different timezones. The server is designed to be lightweight and demonstrates how to create a custom MCP server with practical functionality and proper error handling. It can be deployed either directly on a machine or as a Docker container.

Features

• Get current date and time in any supported timezone
• Optional default timezone configuration through appsettings.json and environment variables
• Proper error handling for invalid timezone requests and missing default timezone
• Functional error handling using Result pattern

Getting Started

Prerequisites

• .NET 10 SDK (for local development or .NET tool installation)
• Docker (for container deployment)

Build Instructions (for development)

If you want to build the project from source:

1. Clone this repository:

   git clone https://github.com/aadversteeg/chronos-mcp-server.git
   

2. Navigate to the project root directory:

   cd chronos-mcp-server
   

3. Build the project using:

   dotnet build src/chronos.sln
   

4. Run the tests:

   dotnet test src/chronos.sln
   

Docker Support

DockerHub Image

The Chronos MCP Server is available on DockerHub at aadversteeg/chronos-mcp-server.

# Pull the latest version
docker pull aadversteeg/chronos-mcp-server:latest

# Or pull a specific version
docker pull aadversteeg/chronos-mcp-server:0.0.1

Manual Docker Build

If you need to build the Docker image yourself:

# Navigate to the repository root
cd chronos-mcp-server

# Build the Docker image
docker build -f src/Core.Infrastructure.McpServer/Dockerfile -t chronos-mcp-server:latest src/

# Run the locally built image (with optional DefaultTimeZoneId)
docker run -d --name chronos-mcp -e "DefaultTimeZoneId=Europe/Amsterdam" chronos-mcp-server:latest

Automated Builds with GitHub Actions

This repository includes a GitHub Actions workflow that automatically builds and pushes the Docker image to DockerHub when a version tag is created.

To trigger a new build:

1. Create and push a tag with a semantic version:

   git tag 1.0.0
   git push origin 1.0.0
   

2. The workflow will automatically build and push the Docker image with the tags:

   • aadversteeg/chronos-mcp-server:latest
   • aadversteeg/chronos-mcp-server:1.0.0

.NET Tool

The Chronos MCP Server is available as a .NET global tool on NuGet.

Installation

dotnet tool install --global Ave.McpServer.Chronos

Running

ave-mcpserver-chronos

One-shot execution (without permanent installation)

With .NET 10 SDK, you can run the tool without installing it globally using dotnet tool exec:

dotnet tool exec -y ave.mcpserver.chronos

The -y flag accepts prompts automatically. The tool is cached locally but not added to your PATH.

MCP Protocol Usage

Client Integration

To connect to the Chronos MCP Server from your applications:

1. Use the Model Context Protocol C# SDK or any MCP-compatible client
2. Configure your client to connect to the server's endpoint
3. Call the available tools described below

Available Tools

get_current_date_and_time

Gets the current date and time in the specified timezone or the default timezone (if configured).

Parameters:

• timezoneId (optional if DefaultTimeZoneId is configured): The timezone identifier (e.g., 'America/New_York', 'Eastern Standard Time'). This parameter is required if no DefaultTimeZoneId is configured.

Example request:

{
  "name": "get_current_date_and_time",
  "parameters": {
    "timezoneId": "Europe/London"
  }
}

Example response:

{
  "date": "2023-12-25",
  "time": "12:00:00",
  "timezone": "Europe/London"
}

get_default_timezone_id

Gets the default timezone identifier configured for the server. Returns an error if no default timezone is configured.

Example request:

{
  "name": "get_default_timezone_id",
  "parameters": {}
}

Example response (if configured):

Europe/Amsterdam

Example error response (if not configured):

{
  "error": {
    "message": "DefaultTimeZoneId is not set.",
    "code": "NoDefaultTimeZoneId"
  }
}

Configuration

DefaultTimeZoneId

The DefaultTimeZoneId setting determines which timezone is used when no specific timezone is requested. This value must be a valid timezone identifier recognized by the operating system. This setting is optional - if not provided, the server will still function but will require a timezone ID parameter for each request.

You can set the DefaultTimeZoneId in two ways:

1. appsettings.json file (for local deployment):

{
  "DefaultTimeZoneId": "America/New_York"
}

2. Environment Variables (for containerized deployments):

# When running the Docker container
docker run -e "DefaultTimeZoneId=Europe/Amsterdam" aadversteeg/chronos-mcp-server:latest

Valid timezone identifiers include:

• Standard IANA timezone names (e.g., "America/New_York", "Europe/London", "Asia/Tokyo")
• Windows timezone IDs (e.g., "Eastern Standard Time", "W. Europe Standard Time")

If the DefaultTimeZoneId setting is not specified, no default timezone will be used, and requests must explicitly provide a timezone ID parameter.

Configuring Claude Desktop / Claude Code

Add the server configuration to the mcpServers section in your configuration file.

Using .NET Tool

Requires .NET 10 SDK. This approach automatically downloads the tool on first use and updates to the latest version on subsequent runs.

"chronos": {
  "command": "dotnet",
  "args": [
    "tool",
    "exec",
    "-y",
    "ave.mcpserver.chronos"
  ],
  "env": {
    "DefaultTimeZoneId": "Europe/Amsterdam"
  }
}

Using Global Installation

Requires .NET 10 SDK. Install the tool once, then use it directly.

dotnet tool install --global Ave.McpServer.Chronos

"chronos": {
  "command": "ave-mcpserver-chronos",
  "env": {
    "DefaultTimeZoneId": "Europe/Amsterdam"
  }
}

To update: dotnet tool update --global Ave.McpServer.Chronos

Using Docker

Does not require .NET 10 SDK.

"chronos": {
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "-e", "DefaultTimeZoneId=Europe/Amsterdam",
    "aadversteeg/chronos-mcp-server:latest"
  ]
}

License

This project is licensed under the MIT License - see the LICENSE file for details.