Gravatar

Gravatar's official MCP Server, enabling access to avatars, profiles, and inferred interests.

For quick installation in VS Code, click one of the installation buttons below:

- Node.js: 20.0.0 or higher
- npm: 10.0.0 or higher

- Node.js 20 (Active LTS)
- Node.js 22 (Current LTS)
- Node.js 24 (Current)

You can install and run this server using npx (recommended) or by building from source.

- Retrieve comprehensive Gravatar profile information using a profile identifier
- Required inputs:

- profileIdentifier(string): A Profile Identifier (seeIdentifier Typessection)

- profileIdentifier(string): A Profile Identifier (seeIdentifier Typessection)

- avatarIdentifier(string): An Avatar Identifier (seeIdentifier Typessection)

Some parts of the Gravatar API can be used without authentication. However, using an API key is recommended as it increases the rate limits for your queries. You can generate your own API key by visiting theDeveloper Dashboard.

{ "mcpServers": { "gravatar": { "command": "npx", "args": [ "-y", "@automattic/mcp-server-gravatar" ], "env": { "GRAVATAR_API_KEY": "your-api-key-here" } } } }

- Without an API key, strict rate limits will be applied.
- A future release of this server may include tools that will only be available with an API key.

{ "mcpServers": { "gravatar": { "command": "npx", "args": [ "-y", "@automattic/mcp-server-gravatar" ] } } }

For manual installation, add one of the following JSON blocks to your User Settings (JSON) file in VS Code. You can do this by pressingCmd + Shift + P(orCtrl + Shift + Pon Windows/Linux) and typingPreferences: Open Settings (JSON).

This configuration prompts for an API key and stores it securely:

{ "mcp": { "inputs": [ { "type": "promptString", "id": "gravatar_api_key", "description": "Gravatar API Key (optional)", "password": true } ], "servers": { "gravatar": { "command": "npx", "args": ["-y", "@automattic/mcp-server-gravatar"], "env": { "GRAVATAR_API_KEY": "${input:gravatar_api_key}" } } } } }

- Without an API key, strict rate limits will be applied.
- A future release of this server may include tools that will only be available with an API key.

{ "mcp": { "servers": { "gravatar": { "command": "npx", "args": ["-y", "@automattic/mcp-server-gravatar"] } } } }

Optionally, you can add either configuration to a file called.vscode/mcp.jsonin your workspace. This will allow you to share the configuration with others.

Note that themcpkey is not needed in the.vscode/mcp.jsonfile.

If you want to build and run the MCP server from local source files:

# Clone the repository git clone https://github.com/Automattic/mcp-server-gravatar.git cd mcp-server-gravatar # Install dependencies npm install

The update your MCP Client configuration:

{ "mcpServers": { "gravatar": { "command": "npx", "args": [ "/path/to/mcp-server-gravatar" ], "env": { "GRAVATAR_API_KEY": "your-api-key-here" } } } }

{ "mcpServers": { "gravatar": { "command": "npx", "args": [ "/path/to/mcp-server-gravatar" ] } } }

The Gravatar MCP server uses different types of identifiers to access profile and avatar data:

AProfile Identifiercan be one of the following:
- SHA256 Hash(preferred): An email address that has been normalized (lower-cased and trimmed) and then hashed with SHA256
- MD5 Hash(deprecated): An email address that has been normalized (lower-cased and trimmed) and then hashed with MD5
- URL Slug: The username portion from a Gravatar profile URL (e.g., 'username' from gravatar.com/username)

AnAvatar Identifieris an email address that has been normalized (lower-cased and trimmed) and then hashed with either:

Important: Unlike Profile Identifiers, Avatar Identifiers cannot use URL slugs - only email hashes are supported.

When using email-based tools, you can provide any valid email format. The system will automatically:
- Normalize the email (convert to lowercase and trim whitespace)
- Generate the appropriate hash for API requests
- Process the email securely without storing it

The MCP Inspector is a tool that helps validate your MCP server implementation. To run the inspector:

This will build the project and then run the MCP Inspector against your server, validating the tools and their schemas.

Start the TypeScript compiler in watch mode:

This will watch for changes to your TypeScript files and automatically recompile them.

This project is tested against multiple Node.js versions to ensure compatibility. The CI pipeline automatically tests on:

- Node.js 20(Active LTS)
- Node.js 22(Current LTS)
- Node.js 24(Current)

To test locally with different Node versions using nvm:

# Test with Node 20 nvm use 20 npm ci npm run type-check npm test # Test with Node 22 nvm use 22 npm ci npm run type-check npm test # Test with Node 24 nvm use 24 npm ci npm run type-check npm test

This project uses aMake-driven architecturefor all code generation with proper file-based dependencies:

# Generate everything (API client + MCP schemas) make generate-all # OR npm run generate-all # Generate just the OpenAPI client make generate-client # OR npm run generate-client # Generate just the MCP schemas (requires client) make generate-schemas # OR npm run generate-schemas

The schema generation is configured viascripts/schemas.config.jsonand supports:

- Configurable schema extractionfrom OpenAPI models
- Array wrappingfor responses that need structured containers
- Clean output schemasthat match MCP specification exactly
- Automatic dependency trackingvia Make

The project includes a Makefile with several useful commands:

- make download-spec: Download the Gravatar OpenAPI spec
- make generate-client: Generate Gravatar API client from OpenAPI spec
- make generate-schemas: Generate MCP output schemas from API client
- make generate-all: Generate API client and MCP schemas
- make build: Build the TypeScript project
- make lint: Run linting
- make lint-fix: Run linting with auto-fix
- make format: Format code with Prettier
- make format-check: Check code formatting
- make quality-check: Run linting and format checking
- make clean: Clean build artifacts and dependencies

Runmake helpto see all available commands.

-

GRAVATAR_API_KEY: Optional API key for Gravatar API. If provided, it will be used for API requests, which increases rate limits and provides access to additional features.

GRAVATAR_API_KEY_ENV_VAR: Optional name of the environment variable that contains the API key. Default isGRAVATAR_API_KEY. This is useful if you need to use a different environment variable name in your deployment environment.

When running the server locally, you can set these environment variables in your shell before starting the server:

# Set API key (recommended) export GRAVATAR_API_KEY=your_api_key_here # Start the server npm start

Or you can provide them inline when starting the server:

GRAVATAR_API_KEY=your_api_key_here npm start

When configuring the server in Claude Desktop or VS Code, you can set these environment variables in the configuration as shown in the Setup section above.

This MCP server is licensed under the Mozilla Public License Version 2.0 (MPL-2.0). This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MPL-2.0. For more details, please see theLICENSEfile in the project repository.

Identity infrastructure for the AI economy. 33-trait psychometric engine — belonging probability, trait vectors, attunement depth. Remote streamable-HTTP. Free tier: 16 tools, 10 req/min.