TakanariShimbo/npx-datetime-mcp-server

| | 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

1. Clone this repository

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

2. Install dependencies

   npm ci
   

3. Build the project

   npm run build
   

4. 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

1. Log in to NPM (create account if needed)

   npm login
   

2. 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

1. Navigate to Repository Settings

   • Go to your GitHub repository
   • Click "Settings" tab
   • Go to "Secrets and variables" → "Actions"

2. 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:

1. 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_)

2. 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

1. Check GitHub Actions

   • Go to "Actions" tab in your repository
   • Verify the "Publish to npm" workflow completed successfully

2. Verify NPM Package

   • Visit: https://www.npmjs.com/package/@takanarishimbo/datetime-mcp-server
   • Or run: npm view @takanarishimbo/datetime-mcp-server

Release Process Flow

1. release.sh script updates version in all files
2. Creates git commit and tag
3. Pushes to GitHub
4. GitHub Actions workflow triggers on new tag
5. Workflow builds project and publishes to NPM
6. 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