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.

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

2. Create a virtual environment:

uv venv
source .venv/bin/activate

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

2. Build package distributions:

uv build

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

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