English | 日本語 | README

DateTime MCP Server

A Model Context Protocol (MCP) server that provides tools to get the current date and time in various formats. This is a TypeScript implementation of the datetime MCP server, demonstrating how to build MCP servers using the TypeScript SDK.

Features

Get current date and time in multiple formats (ISO, Unix timestamp, human-readable, etc.)
Configurable output format via environment variables
Timezone support
Custom date format support
Simple tool: get_current_time

Usage

Choose one of these examples based on your needs:

Basic usage (ISO format):

{
  "mcpServers": {
    "datetime": {
      "command": "npx",
      "args": ["-y", "@takanarishimbo/datetime-mcp-server"]
    }
  }
}

Human-readable format with timezone:

{
  "mcpServers": {
    "datetime": {
      "command": "npx",
      "args": ["-y", "@takanarishimbo/datetime-mcp-server"],
      "env": {
        "DATETIME_FORMAT": "human",
        "TIMEZONE": "America/New_York"
      }
    }
  }
}

Unix timestamp format:

{
  "mcpServers": {
    "datetime": {
      "command": "npx",
      "args": ["-y", "@takanarishimbo/datetime-mcp-server"],
      "env": {
        "DATETIME_FORMAT": "unix",
        "TIMEZONE": "UTC"
      }
    }
  }
}

Custom format:

{
  "mcpServers": {
    "datetime": {
      "command": "npx",
      "args": ["-y", "@takanarishimbo/datetime-mcp-server"],
      "env": {
        "DATETIME_FORMAT": "custom",
        "DATE_FORMAT_STRING": "YYYY/MM/DD HH:mm",
        "TIMEZONE": "Asia/Tokyo"
      }
    }
  }
}

Configuration

The server can be configured using environment variables:

`DATETIME_FORMAT`

Controls the default output format of the datetime (default: "iso")

Supported formats:

iso: ISO 8601 format (2024-01-01T12:00:00.000Z)
unix: Unix timestamp in seconds
unix_ms: Unix timestamp in milliseconds
human: Human-readable format (Mon, Jan 1, 2024 12:00:00 PM)
date: Date only (2024-01-01)
time: Time only (12:00:00)
custom: Custom format using DATE_FORMAT_STRING environment variable

`DATE_FORMAT_STRING`

Custom date format string (only used when DATETIME_FORMAT="custom") Default: "YYYY-MM-DD HH:mm:ss"

Supported tokens:

YYYY: 4-digit year
YY: 2-digit year
MM: 2-digit month
DD: 2-digit day
HH: 2-digit hour (24-hour)
mm: 2-digit minute
ss: 2-digit second

`TIMEZONE`

Timezone to use (default: system timezone) Examples: "UTC", "America/New_York", "Asia/Tokyo"

Available Tools

`get_current_time`

Get the current date and time

Parameters:

format (optional): Output format, overrides DATETIME_FORMAT env var
timezone (optional): Timezone to use, overrides TIMEZONE env var

Development

Clone this repository

git clone https://github.com/TakanariShimbo/npx-datetime-mcp-server.git
cd npx-datetime-mcp-server

Install dependencies
```
npm ci
```
Build the project
```
npm run build
```

Test with MCP Inspector (optional)

npx @modelcontextprotocol/inspector node dist/index.js

Publishing to NPM

This project includes automated NPM publishing via GitHub Actions. To set up publishing:

1. Create NPM Access Token

Log in to NPM (create account if needed)
```
npm login
```
Create Access Token
- Go to https://www.npmjs.com/settings/tokens
- Click "Generate New Token"
- Select "Automation" (for CI/CD usage)
- Choose "Publish" permission level
- Copy the generated token (starts with npm_)

2. Add Token to GitHub Repository

Navigate to Repository Settings
- Go to your GitHub repository
- Click "Settings" tab
- Go to "Secrets and variables" → "Actions"
Add NPM Token
- Click "New repository secret"
- Name: NPM_TOKEN
- Value: Paste your NPM token from step 1
- Click "Add secret"

3. Setup GitHub Personal Access Token (for release script)

The release script needs to push to GitHub, so you'll need a GitHub token:

Create GitHub Personal Access Token
- Go to https://github.com/settings/tokens
- Click "Generate new token" → "Generate new token (classic)"
- Set expiration (recommended: 90 days or custom)
- Select scopes:
  - ✅ repo (Full control of private repositories)
- Click "Generate token"
- Copy the generated token (starts with ghp_)

Configure Git with Token

# Option 1: Use GitHub CLI (recommended)
gh auth login

# Option 2: Configure git to use token
git config --global credential.helper store
# Then when prompted for password, use your token instead

4. Release New Version

Use the included release script to automatically version, tag, and trigger publishing:

# Increment patch version (0.1.0 → 0.1.1)
npm run release patch

# Increment minor version (0.1.0 → 0.2.0)
npm run release minor

# Increment major version (0.1.0 → 1.0.0)
npm run release major

# Set specific version
npm run release 1.2.3

5. Verify Publication

Check GitHub Actions
- Go to "Actions" tab in your repository
- Verify the "Publish to npm" workflow completed successfully
Verify NPM Package
- Visit: https://www.npmjs.com/package/@takanarishimbo/datetime-mcp-server
- Or run: npm view @takanarishimbo/datetime-mcp-server

Release Process Flow

release.sh script updates version in all files
Creates git commit and tag
Pushes to GitHub
GitHub Actions workflow triggers on new tag
Workflow builds project and publishes to NPM
Package becomes available globally via npm install

Creating Desktop Extension (DXT)

Desktop Extensions (.dxt) enable one-click installation of MCP servers in Claude Desktop. To create a DXT file for this server:

1. Initialize DXT Manifest

Run this command in the project root directory:

npx @anthropic-ai/dxt init

This will guide you through creating a manifest.json file. Here are the answers for this project:

✔ Extension name: @takanarishimbo/datetime-mcp-server
✔ Author name: TakanariShimbo
✔ Display name (optional): datetime
✔ Version: 0.3.0
✔ Description: A Model Context Protocol server that returns the current date and time
✔ Add a detailed long description? no
✔ Author email (optional): 
✔ Author URL (optional): 
✔ Homepage URL (optional): https://github.com/TakanariShimbo/npx-datetime-mcp-server
✔ Documentation URL (optional): https://github.com/TakanariShimbo/npx-datetime-mcp-server
✔ Support URL (optional): https://github.com/TakanariShimbo/npx-datetime-mcp-server
✔ Icon file path (optional, relative to manifest): icon.png
✔ Add screenshots? no
✔ Server type: Node.js
✔ Entry point: dist/index.js
✔ Does your MCP Server provide tools you want to advertise (optional)? yes
✔ Tool name: get_current_time
✔ Tool description (optional): Get the current date and time in various formats
✔ Add another tool? no
✔ Does your server generate additional tools at runtime? no
✔ Does your MCP Server provide prompts you want to advertise (optional)? no
✔ Add compatibility constraints? no
✔ Add user-configurable options? no
✔ Keywords (comma-separated, optional): datetime
✔ License: MIT
✔ Add repository information? yes
✔ Repository URL: git+https://github.com/TakanariShimbo/npx-datetime-mcp-server.git

2. Create DXT Package

npx @anthropic-ai/dxt pack

This creates a .dxt file that users can install in Claude Desktop with a single click.

Project Structure

npx-datetime-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── package.json          # Package configuration
├── package-lock.json     # Dependency lock file
├── tsconfig.json         # TypeScript configuration
├── scripts/
│   └── release.sh        # Release automation script
├── .github/
│   └── workflows/
│       └── npm-publish.yml   # NPM publish workflow
├── manifest.json         # MCP server manifest for DXT file
├── icon.png              # icon for DXT file
├── datetime.dxt          # DXT file
├── .gitignore            # Git ignore file
├── docs/
    ├── README.md         # English documentation
    └── README_ja.md      # Japanese documentation

License

MIT