Tipsoi MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Tipsoi MCP Show me the leave balance for employee ID 42"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Tipsoi MCP — Phase 1 (Read-Only)
An MCP server that lets Claude read from the Tipsoi HRM API: employees, attendance, leave, overtime, notifications, and org setup. Phase 1 is strictly read-only — the server registers only GET endpoints, so the assistant physically cannot create, edit, approve, or delete anything.
What's exposed (15 tools)
Tool | Reads |
| Employee directory |
| One employee's profile |
| Monthly attendance report |
| One day's attendance |
| Absentees for a date |
| Late / leave / absent over a range |
| App/selfie punches over a range |
| Leave balances |
| Leave applications (view only) |
| Overtime report |
| Offices/locations |
| Departments |
| Job titles |
| Holidays |
| Recent notifications |
Write endpoints from the API collection (create/update/delete employee, apply/ approve leave, change OT status, etc.) are deliberately not registered. They belong to Phase 2+, behind per-user auth, confirmation, and audit logging.
Related MCP server: humaans-mcp
1. Install
Requires Python 3.10+.
cd tipsoi-mcp
python -m venv .venv && source .venv/bin/activate # optional but recommended
pip install -e .2. Configure credentials
cp .env.example .envEdit .env:
TIPSOI_EMAIL=service-account@yourcompany.com
TIPSOI_PASSWORD=...
TIPSOI_OFFICE_ID=4397 # optional default; discover via list_workplaces
TIPSOI_COMPANY_ID=4146 # optional defaultUse a dedicated read-scoped service account. Whatever this account can see in Tipsoi is the ceiling of what the assistant can read. Even though the server exposes no write tools, scope the account to read-only roles as a second line of defense.
The server reads env vars directly. To load .env, either export the vars in
your shell or use a tool like direnv / dotenv.
3. Test locally (stdio)
set -a; source .env; set +a
python -m tipsoi_mcp.serverIt will start on stdio and wait for an MCP client. Use the MCP Inspector for a quick manual check:
npx @modelcontextprotocol/inspector python -m tipsoi_mcp.serverCall list_workplaces first — it confirms auth works and shows valid
office_id values.
4. Use it as a Claude connector
You have two paths. Local (stdio) is the fastest for one machine; remote (HTTP) is what you want for a shared team connector.
Option A — Local, via Claude Desktop (stdio)
Claude Desktop launches the server as a subprocess.
Open Claude Desktop → Settings → Developer → Edit Config (this opens
claude_desktop_config.json).Add the server:
{
"mcpServers": {
"tipsoi": {
"command": "python",
"args": ["-m", "tipsoi_mcp.server"],
"cwd": "/absolute/path/to/tipsoi-mcp",
"env": {
"TIPSOI_EMAIL": "service-account@yourcompany.com",
"TIPSOI_PASSWORD": "...",
"TIPSOI_OFFICE_ID": "4397",
"TIPSOI_COMPANY_ID": "4146"
}
}
}
} Use the full path to your python (the venv one) if python isn't on
Claude Desktop's PATH — e.g. /path/to/tipsoi-mcp/.venv/bin/python.
Restart Claude Desktop. You'll see a tools/connector icon; "tipsoi" and its 15 tools should appear. Ask: "List our Tipsoi workplaces" or "Show the daily attendance summary for 2026-02-18."
Option B — Remote, via Claude.ai / Claude Desktop Custom Connector (HTTP)
For a connector your team adds by URL, run the server in streamable-HTTP mode behind HTTPS.
Run it in HTTP mode:
set -a; source .env; set +a
TIPSOI_TRANSPORT=http python -m tipsoi_mcp.server FastMCP serves the streamable-HTTP endpoint at /mcp (default host/port
127.0.0.1:8000). Put it behind a reverse proxy (nginx/Caddy) or a tunnel
so it's reachable over HTTPS — remote MCP connectors require TLS.
In Claude: Settings → Connectors → Add custom connector, then paste the public URL, e.g.
https://tipsoi-mcp.yourcompany.com/mcp.Claude lists the tools; enable them and start asking questions.
Phase 1 caveat on remote mode: this build authenticates with a single service account and does not implement OAuth, so every user of the remote connector reads through that one account's permissions. That's acceptable for a read-only internal pilot but must not be how you ship write actions. Per-user OAuth is the first thing Phase 2 adds. Until then, if you deploy remotely, restrict network access (VPN/allowlist) so only your team can reach the endpoint.
Example prompts once connected
"Which employees were absent on 2026-02-18?"
"Give me February 2026 attendance for the Dhaka office."
"Show the overtime report for February 2026."
"What's the leave balance for everyone this quarter?"
"Pull the mobile/selfie punch report for last week."
Design notes
Dates: tools take
YYYY-MM-DD(oryear/month); the server converts to Tipsoi's epoch-millisecond format usingAsia/Dhaka(UTC+6). Override withTIPSOI_TZ_OFFSET_HOURS.Auth refresh: on a 401 the client refreshes the token, then re-signs in if needed — transparent to the caller.
Errors: API/auth failures return a structured
{"error": ...}object instead of throwing, so Claude can explain the problem instead of failing opaquely.
What Phase 2 will add (not in this build)
Per-user OAuth, role-gated write tools (apply/approve leave, OT status, roster edits) behind a preview→confirm step, idempotency keys, and full audit logging of every AI-initiated action.
Available Tools
15 toolsapplied_leave_listARead-only
List applied leave requests and their statuses (READ-ONLY view).
Args: keyword: Optional search term. statuses: List of status codes to include (e.g. [0,1] for pending+approved). Defaults to [0, 1]. page: Zero-based page index. count: Page size.
NOTE: This only reads leave applications. Applying/approving/rejecting leave is a write action and is intentionally NOT available in Phase 1.
Inputs: keyword, statuses, page, count.
daily_absent_reportARead-only
Report of employees absent on a given date.
Args: date: YYYY-MM-DD. office_id: Falls back to TIPSOI_OFFICE_ID if omitted. absent_type: Tipsoi absent classification code (default 1). per_page: Pagination size.
Inputs: date (required), office_id, absent_type, per_page.
daily_attendance_summaryBRead-only
Daily attendance summary for a single date.
Args: date: YYYY-MM-DD. office_id: Falls back to TIPSOI_OFFICE_ID if omitted. employee_name: Optional name filter. status: 1 = active employees. per_page: Pagination size.
Inputs: date (required), office_id, employee_name, status, +1 more.
get_employeeARead-only
Get the basic profile of a single employee by their numeric employee ID.
Args: employee_id: The Tipsoi employee ID (string of digits).
Inputs: employee_id (required).
late_reportARead-only
Late / leave / absent combined report over a date range.
Args: from_date: YYYY-MM-DD (inclusive). to_date: YYYY-MM-DD (inclusive). office_id: Falls back to TIPSOI_OFFICE_ID. company_id: Falls back to TIPSOI_COMPANY_ID. per_page: Pagination size.
Inputs: from_date (required), to_date (required), office_id, company_id, +1 more.
leave_balance_reportBRead-only
Leave balance report across a date range.
Args: from_date: YYYY-MM-DD. to_date: YYYY-MM-DD. office_id: Falls back to TIPSOI_OFFICE_ID. per_page: Pagination size.
Inputs: from_date (required), to_date (required), office_id, per_page.
list_departmentsCRead-only
List departments.
Args: include_inactive: Include inactive departments. Default True.
Inputs: include_inactive.
list_designationsARead-only
List all designations (job titles).
Inputs: no named parameters.
list_employeesARead-only
List employees in the organization.
Args: status: 1 = active, 0 = inactive. Default active. page_number: Zero-based page index. per_page: Records per page (keep modest, e.g. 50-500). order: 'asc' or 'desc'.
Returns the raw employee list payload (id, name, department, etc.). Use this to resolve an employee's name to their numeric ID before calling employee- or report-specific tools.
Inputs: status, page_number, per_page, order.
list_holidaysARead-only
List configured holidays.
Inputs: no named parameters.
list_notificationsARead-only
List recent notifications for the authenticated account.
Args: page_number: Zero-based page index. per_page: Page size.
Inputs: page_number, per_page.
list_workplacesARead-only
List all workplaces (offices/locations) configured in Tipsoi.
Useful for discovering valid office_id values to pass to report tools.
Inputs: no named parameters.
mobile_punch_reportARead-only
Mobile punch (app-based check-in/out, incl. selfie attendance) report.
Args: from_date: YYYY-MM-DD (inclusive). to_date: YYYY-MM-DD (inclusive). office_id: Falls back to TIPSOI_OFFICE_ID. per_page: Pagination size.
Inputs: from_date (required), to_date (required), office_id, per_page.
monthly_attendanceARead-only
Monthly attendance report for an office.
Args: year: e.g. 2026. month: 1-12. office_id: Tipsoi office ID. Falls back to TIPSOI_OFFICE_ID if omitted. employee_name: Optional name filter (substring). status: 1 = active employees. per_page / page_number: Pagination.
Inputs: year (required), month (required), office_id, employee_name, +3 more.
monthly_overtime_reportCRead-only
Monthly overtime report.
Args: year: e.g. 2026. month: 1-12. office_id: Falls back to TIPSOI_OFFICE_ID. company_id: Falls back to TIPSOI_COMPANY_ID. per_page: Pagination size.
Inputs: year (required), month (required), office_id, company_id, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct aspect of HR data: leave requests, attendance reports, employee profiles, lists of departments/designations/workplaces, etc. No two tools have overlapping purposes, making it easy for an agent to select the correct one.
Most tools use a descriptive noun_verb or verb_noun pattern (e.g., 'applied_leave_list', 'list_departments'). There is minor inconsistency: 'get_employee' vs 'list_employees', and some use 'report' suffix while others use 'list'. Overall, the naming is clear and predictable.
15 tools cover the core HR reporting domain—employees, attendance, leave, overtime, notifications—without being excessive. Each tool serves a clear purpose and the count feels well-scoped for a read-only HR API.
The toolset provides comprehensive read access to employee data, attendance reports, leave tracking, and organizational lists. Minor gaps exist (e.g., no individual attendance detail per employee for a specific day beyond summary reports), but the stated Phase 1 scope intentionally excludes write operations, so coverage is appropriate.
Related MCP Connectors
MCP server for Talenta — read employee, attendance, leave, payroll and recruitment data.
Unofficial remote MCP server for Less Annoying CRM: OAuth 2.1, read-only grants, 10 tools.
MCP server for SmartHR — employees, departments, dependents and employee invitations.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA template MCP server built with mcp-framework that provides a foundation for building custom tools. Currently includes example tool implementations that can be extended for HR management system integrations.-
- AlicenseBqualityDmaintenanceRead-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.33MIT
- AlicenseBqualityDmaintenanceMCP server that exposes MAYO Apollo HRM platform's Foundation, Attendance, and Payroll APIs as AI-callable tools, enabling natural language queries for employee profiles, attendance summaries, and payroll reports.33MIT
- AlicenseNot gradedqualityBmaintenanceA comprehensive MCP server that provides AI assistants with full access to FactorialHR to manage employees, teams, time off, projects, training, recruiting, and more, all with built-in safety guardrails.466 npm3MIT