Utility Kit

PyPI version Python 3.13+ License: MIT

An MCP (Model Context Protocol) server built with FastMCP that provides three useful daily utility tools:

Tools Provided

1. Random Joke - Get a random joke of the day
2. Weather Data - Get current weather using latitude and longitude
3. Age Prediction - Predict age based on a person's name

Features

• 🎭 Daily jokes from the Official Joke API
• 🌤️ Real-time weather data from Open-Meteo
• 👤 Name-based age prediction from Agify
• 🚀 Fast and lightweight MCP server
• 📦 Published on PyPI - ready to use
• ⚡ No installation needed with uvx

Quick Start

No installation or cloning required! Just add to your MCP configuration and start using.

Prerequisites

• uv package manager

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation & Setup

Quick Command (Claude CLI)

If you have the Claude CLI installed, add the server with one command:

claude mcp add daily-utils uvx mcp-utility-kit

Option 1: Direct Use with uvx (Recommended)

Use directly without installation:

Add this configuration to your MCP settings file:

VSCode: ~/Library/Application Support/Code/User/mcp.json (Mac) or %APPDATA%\Code\User\mcp.json (Windows)

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)

{
  "mcpServers": {
    "daily-utils": {
      "command": "uvx",
      "args": ["mcp-utility-kit"],
      "type": "stdio"
    }
  }
}

Then reload your MCP client:

• VSCode: Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows) → "Developer: Reload Window"
• Claude Desktop: Restart the application

That's it! The server will automatically download and run.

Option 2: Install via pip

If you prefer traditional installation:

pip install mcp-utility-kit

Then run directly:

python -m mcp_utility_kit

Option 3: Local Development Setup

For contributing or modifying the code:

1. Clone the repository:

git clone https://github.com/thananauto/mcp-utility-kit.git
cd mcp-utility-kit

2. Install dependencies:

uv sync

3. Use local configuration in mcp.json:

{
  "mcpServers": {
    "daily-utils": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/mcp-utility-kit",
        "python",
        "-m",
        "mcp_utility_kit"
      ],
      "type": "stdio"
    }
  }
}

Replace /full/path/to/mcp-utility-kit with your local clone path

Usage

Once configured in your MCP client, you can use these tools through your AI assistant:

• "Tell me a joke" - Gets a random joke
• "What's the weather in New York?" (provide latitude: 40.7128, longitude: -74.0060)
• "Predict the age for the name Michael"

Running Standalone in Terminal

# Run directly with uvx (no install needed)
uvx mcp-utility-kit

# Or if installed via pip
python -m mcp_utility_kit

# From local development
uv run python -m mcp_utility_kit

Testing with MCP Inspector

The MCP Inspector provides a web UI for testing:

# Test published version
npx @modelcontextprotocol/inspector uvx mcp-utility-kit

# Test local version
npx @modelcontextprotocol/inspector uv run python -m mcp_utility_kit

This opens a browser interface where you can test all tools interactively.

Available Tools

1. get_joke_of_the_day()

Gets a random joke from the Official Joke API.

Returns: A formatted joke with setup and punchline

Example:

Why did the chicken cross the road?
To get to the other side!

2. get_weather(latitude: float, longitude: float)

Gets current weather data for a location.

Parameters:

• latitude - Latitude of the location (e.g., 52.52 for Berlin)
• longitude - Longitude of the location (e.g., 13.41 for Berlin)

Returns: Formatted weather summary with temperature, wind speed, humidity, and weather code

Example:

get_weather(latitude=40.7128, longitude=-74.0060)  # New York City

3. predict_age_by_name(name: str)

Predicts the age associated with a given name using the Agify API.

Parameters:

• name - First name to predict age for (e.g., "Michael", "Sarah")

Returns: Predicted age and confidence count

Example:

predict_age_by_name(name="Michael")

APIs Used

This server integrates with the following free APIs:

• Official Joke API - Random jokes
• Open-Meteo Weather API - Weather data (no API key required)
• Agify Age Prediction API - Name-based age prediction

Updating the Package

This package is published on PyPI at: https://pypi.org/project/mcp-utility-kit/

Publishing Updates

To publish a new version:

1. Update version in pyproject.toml:

version = "0.2.0"  # Increment version number

2. Build the package:

uv build

3. Install publishing tools (if not already installed):

uv pip install twine

4. Upload to PyPI:

uv run twine upload -u __token__ -p YOUR_PYPI_TOKEN dist/*

Get your PyPI token from: https://pypi.org/manage/account/token/

Test Before Publishing

Test on Test PyPI first (optional):

uv run twine upload --repository testpypi -u __token__ -p YOUR_TEST_TOKEN dist/*

Sharing with Team Members

Team members can use this server immediately with no installation:

1. Install uv (if needed)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Add MCP Configuration

Add to mcp.json (VSCode) or claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "daily-utils": {
      "command": "uvx",
      "args": ["mcp-utility-kit"],
      "type": "stdio"
    }
  }
}

3. Reload MCP Client

That's it! No cloning, no manual installation needed.

Package Link: https://pypi.org/project/mcp-utility-kit/ Repository: https://github.com/thananauto/mcp-utility-kit

Project Structure

mcp-utility-kit/
├── mcp_utility_kit/
│   ├── __init__.py       # Package initialization
│   ├── server.py         # MCP server implementation with tools
│   └── __main__.py       # Entry point
├── pyproject.toml        # Project configuration and dependencies
├── uv.lock              # Dependency lock file
└── README.md            # This file

Development

Built With

• FastMCP - Framework for building MCP servers
• httpx - Async HTTP client for API requests
• uv - Fast Python package manager

Adding New Tools

To add a new tool to the server:

1. Open mcp_utility_kit/server.py
2. Add a new function decorated with @mcp.tool():

@mcp.tool()
async def your_new_tool(param: str) -> str:
    """Tool description for LLM context.

    Args:
        param: Parameter description

    Returns:
        What the tool returns
    """
    # Your implementation here
    return "result"

3. Test locally with MCP Inspector
4. Rebuild and republish if deploying to PyPI

Troubleshooting

Server Won't Start

1. Check uv is installed:

   uv --version
   

   If not installed: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Test the server directly:

   uvx mcp-utility-kit
   

3. Check MCP configuration: Ensure mcp.json has the correct format (see Installation section)

4. View logs: In VS Code, open Output panel (View → Output) and select "MCP" from dropdown

Tools Not Appearing

• Reload MCP client: In VS Code, press Cmd+Shift+P → "Developer: Reload Window"
• Check server status: Look for "daily-utils" in the MCP Output logs
• Verify configuration: Double-check the JSON syntax in your mcp.json

Package Version Issues

To force update to the latest version:

uvx --refresh mcp-utility-kit

API Errors

• Check internet connection: All three APIs require internet access
• Rate limits: Free tier APIs may have rate limits
• Regional restrictions: Verify APIs are accessible from your location

Getting Help

• Check logs: VS Code Output panel → MCP section shows detailed error messages
• GitHub Issues: https://github.com/thananauto/mcp-utility-kit/issues
• MCP Documentation: https://modelcontextprotocol.io/

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Open an issue in the repository
• Check existing issues for solutions
• Review the MCP documentation