Namely MCP by usefulapi
Read Namely employee profiles, groups, teams, jobs and reports; update profiles, post to the feed.
Should I use this
Quality & Safety
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"namely": {
"url": "https://namely.usefulapi.io/mcp"
}
}
}Remote endpoints
https://namely.usefulapi.io/mcpstreamable-httpWhat it can do
Tool inventory
Tools (17)
🟢namely_get_me
Get the profile of the user the connected token belongs to (name, email, job title, manager, access role). Namely API: GET /profiles/me.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_profiles(page, per_page, format, sort, user_status, ...)
List employee profiles (active, pending and inactive unless filtered) with paging, sorting and filters. Returns {profiles, meta:{count}, linked}. Use format=short for a smaller record (ids, names, email, status, job title); the full record includes every custom field the token may see (compensation, addresses and other sensitive HR data). An empty page means the end. Namely API: GET /profiles (limit 100 requests per minute).
Input Schema
{
"type": "object",
"properties": {
"page": {
"description": "Page number, starting at 1.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"per_page": {
"description": "Profiles per page (default 30, max 50).",
"type": "integer",
"minimum": 1,
"maximum": 50
},
"format": {
"description": "short = truncated profile objects (default); full = every field.",
"type": "string",
"enum": [
"short",
"full"
]
},
"sort": {
"description": "Sort order; a leading - reverses it.",
"type": "string",
"enum": [
"first_name",
"-first_name",
"last_name",
"-last_name",
"created_at",
"-created_at",
"updated_at",
"-updated_at"
]
},
"user_status": {
"description": "Only profiles with this status.",
"type": "string",
"enum": [
"active",
"pending",
"inactive"
]
},
"first_name": {
"description": "Exact first name.",
"type": "string"
},
"last_name": {
"description": "Exact last name.",
"type": "string"
},
"email": {
"description": "Exact company email.",
"type": "string"
},
"personal_email": {
"description": "Exact personal email.",
"type": "string"
},
"job_title": {
"description": "Exact job title (the `title` of a job title).",
"type": "string"
},
"reports_to": {
"description": "Profile id of a manager: only that person's direct reports.",
"type": "string"
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_get_profile(id)
Get one employee's full profile by id: personal and job data, manager, groups, teams and the custom fields the token may see (can include compensation and other sensitive HR data). Namely API: GET /profiles/{id}.
Input Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Namely profile id (the `id` of a profile from namely_list_profiles)."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_profile_fields
List the fields of the employee profile as configured at this company (standard and custom), with their labels, sections and the valid format of each value. Namely API: GET /profiles/fields.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_groups
List all groups (departments, office locations and other company groups). Every group belongs to one group type. Namely API: GET /groups.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_get_group(id)
Get one group by id, with the profiles (members) linked to it. Namely API: GET /groups/{id}.
Input Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Group id (from namely_list_groups)."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_group_types
List the group types (the containers of groups, such as Department or Office). Namely API: GET /group_types.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_teams
List all teams with their team categories. Namely API: GET /teams.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_get_team(id)
Get one team by id, with the profiles (members) linked to it. Namely API: GET /teams/{id}.
Input Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Team id (from namely_list_teams)."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_job_titles
List all job titles; each belongs to one job tier. Namely API: GET /job_titles.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_job_tiers
List all job tiers (the levels that group job titles). Namely API: GET /job_tiers.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_events(type, profile_id, limit, after, order)
List events of the company home feed (announcements, birthdays, work anniversaries, new arrivals), newest first by default, with limit and after (an event id) for paging. Namely API: GET /events.
Input Schema
{
"type": "object",
"properties": {
"type": {
"description": "Event type, e.g. birthday, announcement, recent_arrival, anniversary.",
"type": "string"
},
"profile_id": {
"description": "Only events associated with this profile id.",
"type": "string"
},
"limit": {
"description": "Number of events to return (max 30).",
"type": "integer",
"minimum": 1,
"maximum": 30
},
"after": {
"description": "Event id after which to start (for the next page).",
"type": "string"
},
"order": {
"description": "Order by time; default desc.",
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_list_event_comments(event_id)
List the comments on a feed event. Namely API: GET /events/{event-id}/comments.
Input Schema
{
"type": "object",
"properties": {
"event_id": {
"type": "string",
"minLength": 1,
"description": "Event id (from namely_list_events)."
}
},
"required": [
"event_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢namely_get_report(id)
Run a saved Namely report by id and return its columns and rows (live data; each row is a list in column order). Find the id in the URL of the report in Namely. Reports can contain sensitive HR data such as salary history. Namely API: GET /reports/{id}.
Input Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Report id."
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴namely_update_profile(id, first_name, last_name, email, personal_email, ...)
Change standard fields of an employee profile (name, emails, start date, status, manager, job title). WRITES live HR data. Send only the fields to change. Setting user_status to pending needs a personal_email. Namely API: PUT /profiles/{id}.
Input Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"description": "Namely profile id (the `id` of a profile from namely_list_profiles)."
},
"first_name": {
"description": "First name.",
"type": "string",
"minLength": 1
},
"last_name": {
"description": "Last name.",
"type": "string",
"minLength": 1
},
"email": {
"description": "Company email.",
"type": "string",
"minLength": 3
},
"personal_email": {
"description": "Personal email (required when user_status is pending).",
"type": "string",
"minLength": 3
},
"user_status": {
"description": "active or pending.",
"type": "string",
"enum": [
"active",
"pending"
]
},
"start_date": {
"description": "Start date, YYYY-MM-DD.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"reports_to": {
"description": "Profile id of the new manager.",
"type": "string",
"minLength": 1
},
"job_title": {
"description": "New job title: an object with the id or the exact title of an existing job title.",
"type": "object",
"properties": {
"id": {
"description": "Job title id (guid, from namely_list_job_titles).",
"type": "string",
"minLength": 1
},
"title": {
"description": "Exact job title text (case-sensitive).",
"type": "string",
"minLength": 1
}
}
}
},
"required": [
"id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴namely_create_announcement(content, is_appreciation, email_all)
Post an announcement to the company home feed, visible to every employee. Markdown; to mention a person write [Full Name](/people/<profile_id>). With is_appreciation, mentioned people are appreciated. email_all=true ALSO EMAILS every active employee at their company address (needs the permission) and cannot be undone: set it only when the user explicitly asks. Namely API: POST /events.
Input Schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 10000,
"description": "Announcement text in markdown."
},
"is_appreciation": {
"description": "If true, mentioned profiles are appreciated.",
"type": "boolean"
},
"email_all": {
"description": "If true, also emails all active employees. Default false.",
"type": "boolean"
}
},
"required": [
"content"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴namely_create_event_comment(event_id, content)
Add a comment to a feed event, posted as the token's user and visible to employees who see the event. Markdown; mention a person with [Full Name](/people/<profile_id>). Namely API: POST /events/{id}/comments.
Input Schema
{
"type": "object",
"properties": {
"event_id": {
"type": "string",
"minLength": 1,
"description": "Event id (from namely_list_events)."
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 10000,
"description": "Comment text in markdown."
}
},
"required": [
"event_id",
"content"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Community
Evidence