time-mcp

<p align="center"> <a href="https://github.com/DochertyDev/time-mcp"> <img src="images/apple-touch-icon.png" width="150" alt="Time MCP"> </a> </p>

<h1 align="center"> Time MCP </h1>

<h2 align="center">Effortless system time access, anywhere your LLM needs it.</h2>

<div align="center">

</div>

:star: Love Time MCP? Give us a star to help other developers discover it!

<br />

<div> <img src="images/Time-MCPscreenshot.png" alt="Time MCP Screenshot" width="800" style="border-radius: 16px; box-shadow: 0 20px 40px rgba(0, 0, 0, 0.3), 0 0 0 1px rgba(255, 255, 255, 0.1), inset 0 1px 0 rgba(255, 255, 255, 0.2); transform: perspective(1000px) rotateX(2deg); transition: transform 0.3s ease;"> </div>

---

📋 Table of Contents

• Overview
• Quick Start
• Usage
• Technologies Used
• Security Notes
• Troubleshooting
• Contributing
• Support the Project
• Disclaimer

📄 Overview

Time MCP is a simple and lightweight Model Context Protocol (MCP) server that provides tools to fetch the current date and time from your system. It's perfect for integrating time-related functionality into Claude, Gemini CLI, and other MCP-compatible LLM applications.

This MCP demonstrates core MCP functionality with a focused, practical use case that works reliably across all MCP-compatible platforms.

Features

This MCP provides the following tools:

• get_current_time() - Returns the current time in HH:MM:SS format
• get_current_date() - Returns the current date in YYYY-MM-DD format
• get_current_datetime() - Returns both date and time in ISO 8601 format
• get_time_components() - Returns detailed breakdown of time (year, month, day, hour, minute, second, day of week)
• get_unix_timestamp() - Returns the current Unix timestamp

🚀 Quick Start (Local Development)

Prerequisites

• Python 3.9 or higher
• pip

From PyPI (Recommended)

Once published, you can install directly from PyPI:

pip install time-mcp

From Source (Development)

1. Clone the repository:

   git clone https://github.com/DochertyDev/time-mcp.git
   

2. Navigate to the project directory:

   cd time-mcp
   

3. Install in development mode:

   pip install -e .
   

4. Or install dependencies manually:

   pip install -r requirements.txt
   

Running the Server

To start the MCP server:

python src/server.py

The server will start and wait for incoming MCP protocol connections.

Testing with MCP Inspector

To debug and test your MCP with the MCP Inspector:

mcp dev src/server.py

This will open the MCP Inspector interface where you can test each tool interactively.

⚙️ Usage

Using with Claude Desktop

To add this MCP to Claude Desktop, update your claude_desktop_config.json:

If installed from PyPI:

{
  "mcpServers": {
    "time-mcp": {
      "command": "time-mcp"
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "time-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\time-mcp\\src\\server.py"]
    }
  }
}

Replace C:\path\to\time-mcp with the actual path to your time-mcp directory.

Using with Gemini CLI

Add to your Gemini CLI settings.json:

{
  "mcpServers": {
    "time-mcp": {
      "command": "time-mcp"
    }
  }
}

🛠️ Technologies Used

• FastMCP Framework
• Python 3.9+
• pip

🔒 Security Notes

• This MCP only accesses time-related information from your system
• No file system access
• No network requests
• No external API calls
• No credentials or secrets required

❓ Troubleshooting

Issue: MCP Inspector won't connect

• Solution: Ensure Python 3.9+ is installed and the mcp package is available

Issue: Tools not appearing in Claude

• Solution: Make sure the MCP server is running and properly configured in claude_desktop_config.json

Issue: Import errors

• Solution: Run pip install -r requirements.txt to ensure all dependencies are installed

🤝 Contributing

<div align="center"> <a href="https://github.com/DochertyDev/time-mcp/graphs/contributors"> <img src="https://contrib.rocks/image?repo=DochertyDev/time-mcp&max=400&columns=20" width="100"/> </a> </div>

We welcome contributions from the community! If you have suggestions for improvements or new features, feel free to open an issue or submit a pull request.

🌟 Support the Project

Love Time MCP? Give us a ⭐ on GitHub!

<div align="center"> <p> <img width="800" src="https://api.star-history.com/svg?repos=DochertyDev/time-mcp&type=Date" alt="Star-history"> </p> </div>

If you encounter any issues, please open an issue here.

⚠️ Disclaimer

This project is intended for educational and experimental use. While every effort has been made to ensure its reliability, please use it responsibly and note that the authors cannot provide guarantees for every situation.