Skip to main content
Glama
enesjakozh
bossjones

Datetime MCP Server

by bossjones
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

DateTime MCP Server

A MCP (Model Completions Protocol) server that provides datetime functionality along with simple note management.

Overview

This server implements the MCP protocol and offers various datetime-related tools and resources, including:

  • Current date and time in different formats

  • Date formatting utilities

  • Event scheduling prompts

  • Simple note management functionality

The server can be used by any MCP client to access date and time information and manage simple notes.

Related MCP server: browser-use MCP server

Features

Resources

The server provides the following resources:

  • datetime://current - The current date and time

  • datetime://today - Today's date in ISO format

  • datetime://time - The current time in 24-hour format

  • note://internal/{name} - User-created notes

Tools

The server provides the following tools:

  • add-note - Add a new note with a name and content

  • get-current-time - Get the current time in various formats (ISO, readable, Unix timestamp, RFC3339)

  • format-date - Format a date string according to a specified format pattern

Prompts

The server provides the following prompts:

  • summarize-notes - Creates a summary of all notes

  • schedule-event - Helps schedule an event at a specific time

Installation

  1. Clone the repository:

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

  1. Create a virtual environment:

uv venv
source .venv/bin/activate

  1. Install the dependencies:

uv sync

Usage

Running the Server

To run the server:

uv run python -m datetime_mcp_server.server

The server will start and listen on stdin/stdout for MCP protocol messages.

Connecting to the Server

You can connect to the server using any MCP client. For example, using the MCP CLI:

uv run mcp connect datetime-mcp-server

Development

Installing Development Dependencies

# Install all dependencies including development dependencies
uv sync --dev

Running Tests

To run the tests:

uv run pytest tests/

Unit Tests

Unit tests verify that individual server functions work correctly:

uv run pytest tests/acceptance/test_server.py

Integration Tests

Integration tests verify that the server implements the MCP protocol correctly:

uv run pytest tests/acceptance/test_server_integration.py

Dependency Management

# Add a production dependency
uv add package_name

# Add a development dependency
uv add --dev package_name

# Sync dependencies from lockfile
uv sync --frozen

# List outdated packages
uv outdated

Examples

Using the Server with MCP CLI

List available resources:

uv run mcp resources list

Read a datetime resource:

uv run mcp resources read datetime://current

Add a note:

uv run mcp tools call add-note --arguments '{"name": "meeting", "content": "Team meeting at 3pm"}'

Get the current time in ISO format:

uv run mcp tools call get-current-time --arguments '{"format": "iso"}'

Format a date:

uv run mcp tools call format-date --arguments '{"date": "2023-10-15", "format": "%B %d, %Y"}'

Makefile Tasks

The project includes several Makefile tasks to streamline development:

# Sync all dependencies with frozen lockfile
make uv-sync-all

# Sync only development dependencies
make uv-sync-dev

# Run tests
make test

Building and Publishing

To prepare the package for distribution:

  1. Sync dependencies and update lockfile:

uv sync

  1. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

  1. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

  • Token: --token or UV_PUBLISH_TOKEN

  • Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/malcolm/dev/bossjones/datetime-mcp-server run datetime-mcp-server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

License

MIT

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Run the tests with uv run pytest

  5. Submit a pull request

Available Tools

3 tools
add-noteC

Add a new note

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
contentYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Add a new note' and provides no details on side effects, permissions, return values, or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence with no wasted words, making it concise and front-loaded. However, it is under-specified for the tool's complexity, though this is largely a completeness issue rather than a conciseness issue.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, output schema, and parameter descriptions, a five-word description is insufficient for an agent to invoke the tool correctly. The meaning of the parameters and expected return behavior remain ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero description coverage for the two required parameters ('name' and 'content'), and the description does not explain their meaning or format. The agent cannot infer what 'name' or 'content' represent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Add') and a specific resource ('note'), clearly stating the tool's function. It differentiates itself from the sibling 'get_report', which is a read operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description only states the action without any context about when to invoke it or when to choose a sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

format-dateC

Format a date string according to the specified format

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoDate string to format (default: today)
formatYesFormat string (e.g., '%Y-%m-%d %H:%M:%S')

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does but doesn't cover important aspects like error handling, input validation, timezone considerations, or output format details. This is inadequate for a tool with potential complexity in date parsing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that states the core functionality without any wasted words. It's appropriately sized for this simple tool and gets straight to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a date formatting tool with no annotations and no output schema, the description is insufficient. It doesn't explain what format strings are supported, how date strings should be formatted, what happens with invalid inputs, or what the output looks like. The agent would need to guess about important behavioral aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('format') and resource ('date string'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get-current-time' which might also handle date/time operations, so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention sibling tools or contexts where this formatting operation is appropriate, leaving the agent without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-current-timeB

Get the current time in various formats

ParametersJSON Schema
NameRequiredDescriptionDefault
formatYesFormat to return the time in
timezoneNoOptional timezone (default: local system timezone)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool returns time 'in various formats' but doesn't specify what those formats are, whether the operation is read-only, if there are rate limits, or how errors are handled. This leaves significant behavioral aspects unclear for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple tool and front-loads the core functionality, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two parameters and no output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavioral aspects like error handling or return formats, which would help the agent use it correctly despite the absence of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'various formats', which aligns with the 'format' parameter's enum values in the schema. However, with 100% schema description coverage, the schema already documents both parameters thoroughly. The description adds minimal value beyond what the structured schema provides, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose ('Get the current time') and specifies the scope ('in various formats'), which distinguishes it from potential time-related operations. However, it doesn't explicitly differentiate from sibling tools like 'format-date', which might handle date formatting rather than current time retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'format-date'. It doesn't mention prerequisites, limitations, or scenarios where this tool is preferred, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updates
    • First observedadd-note
    • First observedformat-date
    • First observedget-current-time
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: add-note handles note creation, format-date processes date formatting, and get-current-time retrieves current time. The descriptions are specific and unambiguous, making tool selection straightforward for an agent.

Naming Consistency2/5

The naming is inconsistent with mixed conventions: add-note uses kebab-case, format-date uses kebab-case, and get-current-time uses kebab-case but has a longer name. While all are kebab-case, the verb styles vary (add, format, get), and the lack of a uniform pattern (e.g., all starting with 'get_' or using consistent verb forms) reduces predictability.

Tool Count3/5

With only 3 tools, the count feels thin for a 'Datetime MCP Server' as it suggests limited functionality. While the tools cover basic datetime operations, the server's name implies a broader scope that might include more operations like date parsing, timezone handling, or interval calculations, making this borderline appropriate.

Completeness2/5

The tool surface has significant gaps for a datetime server: it lacks core operations such as parsing dates, calculating differences between dates, handling timezones, or converting between formats. The existing tools (add-note, format-date, get-current-time) do not provide a complete CRUD/lifecycle coverage for datetime manipulation, leading to potential agent failures in common scenarios.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches