Smarthr MCP Server

The SmartHR MCP Server project provides a model context protocol service for interfacing with the SmartHR API, supporting the operation and management of data such as employees, departments, and positions.

Customer data platform Developer tools #Personnel management #API docking #Data synchronization #Enterprise services .Python

rating : 2 points

downloads : 19

update time : 2025-04-28

What is the SmartHR MCP Server?

This is a middleware server based on the Model Context Protocol (MCP), specifically designed to interface with the SmartHR human resources management system. It allows non-technical users to access and manage HR data such as employee information and organizational structure through standardized interfaces.

How to use the SmartHR MCP Server?

Simply perform simple environment configuration and API key settings, and you can access all HR data functions through client tools that support the MCP protocol, such as Claude.

Applicable scenarios

Suitable for scenarios where SmartHR data needs to be integrated into other systems, such as employee self-service portals, data analysis platforms, or automated workflow systems.

Main features

Comprehensive data accessSupports reading and modifying all core HR data such as employees, departments, positions, and employment types

Complete CRUD operationsProvides complete data operation functions such as create, read, update, and delete

Advanced searchSupports filtering and searching employee information by multiple conditions

Advantages and limitations

Advantages

Simplify the complex interfaces of the SmartHR API

Standardize the data access method

Support integration with multiple client tools

Limitations

Requires a SmartHR enterprise account and API permissions

Some advanced features require additional configuration

How to use

Get an API key

Obtain a valid API access token from the SmartHR developer portal

Configure the environment

Create a.env file and set necessary parameters such as SMARTHR_API_KEY

Start the service

Run the main program to start the MCP server

Client configuration

Import the smarthr_mcp_server.json configuration file in client tools such as Claude

Usage examples

New employee onboardingAutomatically create a new employee record and assign a department through the MCP server

Organizational structure analysisGet statistics on the number of employees in each department

Frequently Asked Questions

What permissions are required to use this service?

Which client tools are supported?

Is data synchronization real-time?

Related resources

SmartHR developer documentation

Official API documentation and development guides

MCP protocol specification

Technical specification of the Model Context Protocol

Example code repository

Usage examples and code snippets

🚀 SmartHR MCP Server

This project implements an MCP (Model Context Protocol) server for the SmartHR API. It enables the handling of SmartHR's employee, department, position, employment type, and grade information as MCP tools.

🚀 Quick Start

✨ Features

This project provides an MCP server for SmartHR API, allowing users to manage various SmartHR information through MCP tools.

📦 Installation

Clone or download the repository
Set environment variables (.env) To communicate with the SmartHR API, the following environment variables are required:
```
SMARTHR_API_BASE_URL=https://app.smarthr.jp/api
SMARTHR_API_KEY=YOUR_SMARTHR_API_TOKEN
```

💻 Usage Examples

Basic Usage

Claude for Desktop Configuration Add the contents of smarthr_mcp_server.json to claud_desktop_config.json.
Restart Claude for Desktop
```
% killall "Claude"
% open -a Claude
```

📚 Documentation

Component Structure

smarthr-mcp-server/
│
├── .env_sample
├── .gitignore
├── main.py
├── pyproject.toml
├── README.md
├── requirements.txt
├── smarthr_mcp_server.json         # Definition and command information of MCP tools (for MCP-compatible clients)
├── uv.lock
│
└── smarthr_mcp_server/
    ├── server.py                   # MCP server implementation based on FastMCP
    ├── smarthr_client.py          # Client module responsible for communicating with the SmartHR API
    └── smarthr_mcp_server.egg-info/

Supported Tools List

Registration-related

Function Name	Description
`smarthr_create_crew()`	Create an employee
`smarthr_create_department()`	Create a department
`smarthr_create_position()`	Create a position
`smarthr_create_employment_type()`	Create an employment type
`smarthr_create_grade()`	Create a grade

Deletion-related

Function Name	Description
`smarthr_delete_crew()`	Delete an employee
`smarthr_delete_department()`	Delete a department
`smarthr_delete_position()`	Delete a position
`smarthr_delete_employment_type()`	Delete an employment type
`smarthr_delete_grade()`	Delete a grade

Retrieval-related

Function Name	Description
`smarthr_get_crew()`	Get employee information
`smarthr_get_departments()`	Get all departments
`smarthr_get_positions()`	Get all positions
`smarthr_get_employment_types()`	Get all employment types
`smarthr_get_grades()`	Get all grades

Listing-related

Function Name	Description
`smarthr_list_relations()`	Get the relationship list

Search-related

Function Name	Description
`smarthr_search_crews()`	Search for employees

Update-related

Function Name	Description
`smarthr_update_crew()`	Update employee information
`smarthr_update_department()`	Update department information
`smarthr_update_position()`	Update position information
`smarthr_update_employment_type()`	Update employment type
`smarthr_update_grade()`	Update grade information

Partial Update-related

Function Name	Description
`smarthr_partial_update_department()`	Partially update department information
`smarthr_partial_update_position()`	Partially update position information
`smarthr_partial_update_employment_type()`	Partially update employment type
`smarthr_partial_update_grade()`	Partially update grade information

📄 License

This project is licensed under the MIT license.

⚠️ Important Note

All actions taken using this program and any resulting damages and losses are the sole responsibility of the user. The project party shall not assume any liability.