MCP Server Gravatar

🚀 Gravatar's MCP Server

A Model Context Protocol (MCP) server based on standard input-output (stdio) that provides access to Gravatar profile and avatar data. Clients (e.g., Claude Desktop, custom IDE plugins) can discover and invoke the tool via the MCP protocol to obtain Gravatar profiles and avatars.

🚀 Quick Start

This server allows clients to access Gravatar profile and avatar data through the MCP protocol.

✨ Features

• Retrieve Gravatar profiles by email or SHA256 hash.
• Retrieve specific profile fields.
• List user avatars and obtain avatar image bytes.
• Run via stdio for easy integration with MCP-compatible clients.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• The uv CLI tool installed (provides uv sync and uv run commands).
• (Optional) Docker, if you need to regenerate the OpenAPI client via make generate.

Setup Steps

1. Clone the repository

   git clone https://github.com/andrewdmontgomery/mcp-server-gravatar.git
   cd mcp-server-gravatar
   

2. Install dependencies

   uv sync
   

   This command installs all Python packages into the active virtual environment according to the dependencies specified in pyproject.toml.

3. Generate the OpenAPI client (if you've updated openapi.yaml)

   ⚠️ Important Note

   Manual modifications have been made to the generated code to fix issues. If you regenerate the openapi_client, please preserve these changes.

   make generate
   

   This command runs the OpenAPI Generator Docker image and synchronizes the generated openapi_client to src/openapi_client.

📚 Documentation

Configuration

Usage in Claude Desktop

Add the following content to your claude_desktop_config.json file:

"mcpServers": {
  "git": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/andrewdmontgomery/mcp-server-gravatar", "mcp-server-git"]
  }
}

Running the MCP Server

You can run the server directly as a module:

# Start the MCP server
uv run -m mcp_server_gravatar

Debugging with the MCP Monitor

You can track and debug the execution of prompts and tools through the MCP monitor. For example:

1. Run the monitor:

   npx @modelcontextprotocol/inspector uv run mcp-server-gravatar
   Starting MCP inspector...
   ⚙️  The proxy server is listening on port 6277.
   🔍 The MCP monitor is running at http://127.0.0.1:6274.
   

2. Open the monitor UI in your browser
   • In the above example: http://localhost:6274

For more detailed information, please refer to the official documentation: https://modelcontextprotocol.io/docs/tools/inspector

Makefile Targets

• make generate — Regenerate and synchronize the OpenAPI client.
• make clean — Delete the generated client files.

Environment Variables

• GRAVATAR_API_TOKEN — Your Gravatar API key.