# SmartHR MCP

> SmartHR connects your organization's sensitive employee database directly to any AI client. You can query roster details, organizational structure, payroll records, and even dependent information using plain language. It lets you access deep HR data without ever switching tabs or logging into the SmartHR portal.

## Overview
- **Category:** human-resources
- **Price:** Free
- **Tags:** employee-management, payroll, organizational-chart, labor-management, hr-compliance

## Description

Your AI agent interacts with your company's human capital records through natural conversation. Instead of navigating complex web portals just to find out a department structure or someone’s employment type, you ask the question and get the answer instantly. This MCP reads your internal database directly.

Whether you need an overview of all employees, want to check payroll histories, or track specific job roles across multiple locations, everything is accessible from one place. It takes the friction out of managing sensitive organizational data, letting you focus on the insights rather than the clicks. Vinkius hosts this catalog so your AI agent can access powerful tools like this without needing dozens of separate subscriptions.

It’s designed for deep querying: check employee rosters using list_crews to get a full headcount, or use list_departments and list_positions together if you need to map out internal hierarchies. You'll find it significantly faster than any manual process.

## Tools

### list_crews
Retrieves a full roster of all current employees in the system.

### get_crew_details
Pulls comprehensive data for one specific employee using their internal ID.

### list_departments
Lists every organizational department defined within the company structure.

### list_positions
Provides a list of all official job titles or roles available in the organization.

### list_employment_types
Shows all recognized employment statuses (e.g., full-time, contract).

### list_payrolls
Generates a list of recorded payroll records for various employees.

### list_establishments
Lists all registered business locations or office branches the company operates.

### list_crew_dependents
Fetches details about dependents linked to a specific employee profile.

## Prompt Examples

**Prompt:** 
```
Fetch the entire roster and list the top 3 job positions that occur most frequently.
```

**Response:** 
```
I've fetched the crew and positions. Out of 150 current employees, the top 3 most common job positions in your organization are:
1. Entry-Level Developer (42 members)
2. QA Specialist (18 members)
3. Account Executive (15 members)
```

**Prompt:** 
```
Retrieve the details for crew member `crew-8f192`, including their enrolled dependents.
```

**Response:** 
```
Here's the SmartHR profile for Crew `crew-8f192`:
- **Name**: Yuto Tanaka
- **Department**: Engineering Div.
- **Employment Type**: Full-Time Employee

**Dependents Listed**:
- 1 Registered Dependent (Spouse). ID: `dep-43X`
```

**Prompt:** 
```
List all physical establishments the company operates.
```

**Response:** 
```
From the endpoint results, your company operates 2 registered business establishments:
1. Tokyo Shibuya Headquarters (Est. Code: HQ-1)
2. Fukuoka Branch Office (Est. Code: FB-2)

Do you want me to map employees to these branches?
```

## Capabilities

### Get a complete roster of all employees
Retrieves the full list of current staff members along with their basic metadata.

### Map out the company's internal structure
Lists all official departments and job positions, helping you understand how roles fit together organizationally.

### View sensitive employee records
Fetches detailed information about a specific person, including their employment status or registered dependents.

### Audit compensation and payroll data
Securely queries both active and historical payroll ledgers for compliance checks and reporting.

### Determine physical office locations
Provides a list of all registered business establishments or branch offices the company operates.

## Use Cases

### Auditing a team's compensation
The HR Manager needs to check if all employees in the Sales department are on the correct pay scale. They ask the agent to cross-reference list_departments, list_positions, and then query list_payrolls for anomalies.

### Onboarding a new team member
A Department Lead asks the AI agent who reports into their newly created division. The agent uses list_positions to confirm the role exists and then pulls relevant crew data using list_crews for immediate visibility.

### Checking compliance for international staff
A Security Team member needs to know if an employee has registered dependents while also checking if that employee lives at a specific branch. They query get_crew_details and list_establishments together.

## Benefits

- Stop switching tabs. Instead of clicking through multiple screens to find out who reports to whom, ask the agent directly for organizational structure details by listing departments and positions.
- Audit payroll records instantly. You can use list_payrolls to check historical compensation data without having to export a file or query the finance system manually.
- Get deep employee context fast. Need to know about an individual? The get_crew_details tool pulls all primary information, including dependents listed by list_crew_dependents, in one go.
- Map your company footprint easily. Use list_establishments if you need to confirm which office locations are active or how many branches the business has set up.
- Handle compliance checks better. By accessing both list_employment_types and get_crew_details, you can verify employee status alongside their basic profile data.

## How It Works

The bottom line is you talk to your AI client like talking to an HR partner, and it pulls data straight from SmartHR without any manual steps on your end.

1. Subscribe to this MCP and provide your SmartHR Access Token and Subdomain credentials.
2. Connect your preferred AI client (like Claude, Cursor, etc.) to the Vinkius catalog via the MCP connection.
3. Ask your agent a natural language question; it uses the available tools to query your employee database and deliver the summarized answer.

## Frequently Asked Questions

**Can I use SmartHR MCP to find out how many employees work at a specific branch?**
Yes. You can combine list_establishments with list_crews by asking your agent for the employee count associated with a given location code.

**Does SmartHR MCP show me salary information?**
It shows payroll records using list_payrolls, which means you can audit compensation scaling and view historical pay data. However, it doesn't give general salary estimates.

**How do I find out an employee's job role or title?**
The MCP uses list_positions to show all official roles available in the company. You can then cross-reference this with get_crew_details for specific employees.

**Is SmartHR MCP secure enough for sensitive payroll data?**
Yes, it is designed to securely query your internal database through natural language interfaces, keeping the interaction within your controlled AI client environment.