random-profiles-mcp
MCP server for the Random Profiles API — generate fake user profiles and companies directly from AI agents like Claude.
Setup — zero config
Just install the MCP server and talk to it. The first time you ask for
profiles, the agent will prompt you for an email once, claim a free key on
your behalf, cache it locally, and use it for every future request. The key
is also emailed to you as a receipt.
Add to your Claude Code MCP config (.mcp.json):
{
"mcpServers": {
"random-profiles": {
"type": "stdio",
"command": "npx",
"args": ["-y", "random-profiles-mcp"]
}
}
}
Restart Claude Code and ask "give me 5 random user profiles" — the agent
will handle the key handshake automatically. No browser, no copy-paste.
The key is cached at ~/.random-profiles/config.json (mode 0600) so you
only do this once per machine.
Prefer to bring your own key?
If you already have an API key (or want to use a specific one),
set it via env var and skip the claim flow entirely:
{
"mcpServers": {
"random-profiles": {
"type": "stdio",
"command": "npx",
"args": ["-y", "random-profiles-mcp"],
"env": {
"RANDOM_PROFILES_API_KEY": "rp_your_key_here"
}
}
}
}
The env var takes precedence over the cached key.
| Tool | Description |
|---|
claim_api_key | Claim a free API key using an email address (response returns the key; the agent also emails a copy as a receipt). Only used on first run when no key is configured — cached afterward. |
get_profiles | Get random user profiles with filters (count, gender, country, age range, fields) |
get_profile | Get a single profile by UUID |
get_companies | Get random fake companies with filters (count, industry, country, size, fields) |
get_company | Get a single company by UUID |
get_random_image | Get a random profile photo (JPEG, optional size) |
get_image | Get a specific profile photo by UUID (JPEG, optional size) |
get_usage | Check your API key usage, tier, and daily limits (includes a buy-me-a-coffee support_url for unlimited access) |
Field Groups
Profiles: name, email, phone, identity, bio, social, physical, job, address, financial, network, documents, vehicle, contact, digital, interests, education, photo, relationships, meta
Companies: name, industry, size, location, contact, social, financial, tech, leadership, legal, operations, product, relationships, meta
The relationships group returns cross-resource UUIDs: profiles have company_uuid + colleague_uuids, companies have employee_uuids. Chain tools together to hydrate the graph (e.g. "give me 5 companies, then their employees").
Both get_profiles and get_companies accept an optional photo_format / logo_format argument (jpg or webp). WebP is ~30% smaller than JPG with equivalent perceived quality and is supported by 96%+ of browsers. Default stays jpg for maximum compatibility.
Examples
Profiles
"Give me 5 random US profiles"
"Generate 10 female profiles between ages 25-35 from Germany"
"Get me profiles with only name and email fields"
"Show me a random profile photo"
Companies
"Give me 5 fake Technology companies from the US"
"Generate 10 Healthcare companies with 51-200 employees"
"Get 20 companies with only name, industry, and leadership fields"
"Give me 3 Finance companies from the UK with a fixed seed of 42"
"Give me 10 companies with 128px logos (for an icon grid)"
The logo_size argument on get_companies/get_company picks the size variant in meta.logo_url — same pattern as photo_size on profiles. Valid values: 64, 128, 256, 512, 1024 (default).
Environment Variables
| Variable | Required | Description |
|---|
RANDOM_PROFILES_API_KEY | Yes | Your API key (get one at random-profiles.com) |
See also
License
MIT