mcp-device-datetime: Instructions file for Claude Code

Project Guidelines

Overview

Python MCP server exposing the host device's wall clock datetime. Uses the mcp SDK with the FastMCP high-level API.

Project Structure

Source lives in mcp_device_datetime/ at the repo root (no src/ directory).

• mcp_device_datetime/server.py — FastMCP instance, tool definitions, entry point
• mcp_device_datetime/__init__.py — empty package marker
• mcp_device_datetime/__main__.py — enables python -m mcp_device_datetime
• pyproject.toml — setuptools backend, requires-python = ">=3.10", not yet on PyPI
• README.md, CLAUDE.md, .gitignore

Tooling

• Package manager: pip only — do not use uv
• Build backend: setuptools
• Only external dependency: mcp

Development

pip install -e .
python -m mcp_device_datetime   # run server
pip install "mcp[cli]" && mcp dev mcp_device_datetime/server.py  # MCP Inspector

Claude Desktop Installation

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "device-datetime": {
      "command": "mcp-device-datetime"
    }
  }
}

If Claude Desktop doesn't inherit the active environment, use the full path from which mcp-device-datetime.

Tools

Both return an ISO 8601 string with second precision and timezone offset.

• get_device_local_datetime — local time (e.g. 2026-02-23T14:30:45-08:00)
• get_device_utc_datetime — UTC time (e.g. 2026-02-23T22:30:45+00:00)

Conventions

• Register tools with @mcp.tool() on plain functions in server.py
• Tool names: get_device_ prefix followed by what is returned
• Return type: str; always timezone-aware ISO 8601 with timespec="seconds"
• Stdlib only inside tool implementations — no third-party packages
• Never write to stdout (corrupts JSON-RPC); use stderr for debug output