MCP Utility Kit

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

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
• 📦 Installable via PyPI or local development

Installation

Prerequisites

• Python 3.13 or higher
• uv package manager (recommended)

Option 1: Install from PyPI (After Publishing)

pip install mcp-utility-kit

Or use directly with uvx (no installation needed):

uvx mcp-utility-kit

Option 2: Local Development Setup

1. Clone the repository:

git clone <repository-url>
cd mcp-utility-kit

2. Install dependencies:

uv sync

MCP Client Configuration

For Local Development

Add to your MCP configuration 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": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/mcp-utility-kit",
        "python",
        "-m",
        "mcp_utility_kit"
      ],
      "type": "stdio"
    }
  }
}

Note: Replace /full/path/to/mcp-utility-kit with the actual path where you cloned this repository.

After Publishing to PyPI

Once published, your team can use the simpler configuration:

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

Reload Your MCP Client

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

Usage

Running Locally in Terminal

# From the project directory
cd /path/to/mcp-utility-kit

# Run with uv
uv run python -m mcp_utility_kit

# Or directly with Python
python -m mcp_utility_kit

Testing with MCP Inspector

The MCP Inspector provides a web UI for testing your MCP server:

npx @modelcontextprotocol/inspector uv run --directory /path/to/mcp-utility-kit python -m mcp_utility_kit

This opens a browser interface where you can test all the 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

Publishing to PyPI

To publish this package to PyPI for easy team distribution:

1. Prepare for Publishing

Update the package information in pyproject.toml:

• Update authors with your information
• Update project.urls with your repository URLs
• Increment the version number for updates

2. Build the Package

uv build

This creates distribution files in the dist/ directory.

3. Publish to PyPI

Install publishing tools:

pip install twine

Upload to PyPI (requires PyPI account and credentials):

twine upload dist/*

Or upload to Test PyPI first:

twine upload --repository testpypi dist/*

4. Verify Installation

After publishing, test the installation:

pip install mcp-utility-kit

# Or use directly
uvx mcp-utility-kit

Sharing with Team Members

Option 1: Via PyPI (Recommended)

Once published to PyPI, team members can use it immediately:

1. No clone needed - uvx will automatically download and run it
2. Simple configuration - Add to mcp.json:

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

3. Reload MCP client - Done!

Option 2: Via Git Repository

For development or before PyPI publishing:

1. Share the repository:

   • Push to GitHub, GitLab, or your internal Git server
   • Share the repository URL

2. Team members install:

git clone <repository-url>
cd mcp-utility-kit
uv sync

3. Configure MCP client with local path (see configuration section above)

4. Reload MCP client

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

• Verify Python 3.13+ is installed: python --version
• Check configuration path in mcp.json is correct
• Ensure uv is installed: uv --version
• Try running directly: uv run python -m mcp_utility_kit

Tools Not Appearing

• Reload your MCP client
• Check server logs in VS Code Output panel (MCP section)
• Verify the server started successfully

API Errors

• Check your internet connection
• Verify the APIs are accessible (no regional restrictions)
• Check API response in terminal by running server directly

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