MCP Server for Gravatar

A stdio-based Model Context Protocol (MCP) server that provides access to Gravatar profile and avatar data. Clients (e.g., Claude Desktop, custom IDE plugins) can discover and invoke tools via MCP to fetch Gravatar profiles and avatars.

Features

• Fetch Gravatar profile by email or SHA256 hash
• Retrieve specific profile fields
• List user avatars and fetch avatar image bytes
• Works over stdio for easy integration with MCP-aware clients

Prerequisites

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

Setup

1. Clone the repository

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

2. Install dependencies

uv sync

This will install all Python dependencies specified in `pyproject.toml` into your active virtual environment.

Regenerating the OpenAPI client

(if you’ve updated `openapi.yaml`)

> [!CAUTION]

> Regenerating the client will cause problems. There are manual changes that have been applied to the generated code in order to fix issues.

> If you re-generate the openapi_client, those changes should be retained. Ideally these changes would by applied as a post-generation step.

make generate

This runs the OpenAPI Generator Docker image and synchronizes the generated `gravatar_api_client/openapi_client` into `src/openapi_client`.

Configuration

Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

Using uvx

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

Or if you want to load a specific branch (e.g. `add/my-feature`):

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

Running the MCP Server

You can start the server directly:

# Run the MCP server
uv run mcp-server-gravatar

This can be helpful for debugging startup issues.

With `uvx`, you can also start the server from the repo:

uvx --from git+https://github.com/andrewdmontgomery/mcp-server-gravatar mcp-server-gravatar

You can specify a branch, too (e.g. `add/my-feature`):

uvx --from git+https://github.com/andrewdmontgomery/mcp-server-gravatar@add/my-feature mcp-server-gravatar

Debugging with MCP Inspector

You can use the MCP Inspector to trace and debug prompt and tool executions. For example:

1. Run Inspector:

make inspector

Or manually:

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

3. Open the Inspector UI in your browser

For more details, see the official docs:

https://modelcontextprotocol.io/docs/tools/inspector

Makefile Targets

• `make generate` — regenerate and sync the OpenAPI client
• `make clean` — remove generated client files

Environment Variables

• `GRAVATAR_API_TOKEN` — your Gravatar API key