Content
# 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](https://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:
```bash
git clone https://github.com/aadversteeg/chronos-mcp-server.git
```
2. Navigate to the project root directory:
```bash
cd chronos-mcp-server
```
3. Build the project using:
```bash
dotnet build src/chronos.sln
```
4. Run the tests:
```bash
dotnet test src/chronos.sln
```
## Docker Support
### DockerHub Image
The Chronos MCP Server is available on DockerHub at `aadversteeg/chronos-mcp-server`.
```bash
# 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:
```bash
# 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:
```bash
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
```bash
dotnet tool install --global Ave.McpServer.Chronos
```
### Running
```bash
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`:
```bash
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:
```json
{
"name": "get_current_date_and_time",
"parameters": {
"timezoneId": "Europe/London"
}
}
```
Example response:
```json
{
"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:
```json
{
"name": "get_default_timezone_id",
"parameters": {}
}
```
Example response (if configured):
```
Europe/Amsterdam
```
Example error response (if not configured):
```json
{
"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):
```json
{
"DefaultTimeZoneId": "America/New_York"
}
```
2. **Environment Variables** (for containerized deployments):
```bash
# 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.
```json
"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.
```bash
dotnet tool install --global Ave.McpServer.Chronos
```
```json
"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.
```json
"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](LICENSE) file for details.
