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 timedatetime://today- Today's date in ISO formatdatetime://time- The current time in 24-hour formatnote://internal/{name}- User-created notes
Tools
The server provides the following tools:
add-note- Add a new note with a name and contentget-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 notesschedule-event- Helps schedule an event at a specific time
Installation
- Clone the repository:
git clone https://github.com/bossjones/datetime-mcp-server.git
cd datetime-mcp-server
- Create a virtual environment:
uv venv
source .venv/bin/activate
- 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:
- Sync dependencies and update lockfile:
uv sync
- Build package distributions:
uv build
This will create source and wheel distributions in the dist/ directory.
- Publish to PyPI:
uv publish
Note: You'll need to set PyPI credentials via environment variables or command flags:
- Token:
--tokenorUV_PUBLISH_TOKEN - Or username/password:
--username/UV_PUBLISH_USERNAMEand--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
- Fork the repository
- Create a feature branch
- Make your changes
- Run the tests with
uv run pytest - Submit a pull request