Skip to main content
Glama
Tipsoi MCP

Tipsoi MCP

by the-abraar

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

list_employees

Employee directory

get_employee

One employee's profile

monthly_attendance

Monthly attendance report

daily_attendance_summary

One day's attendance

daily_absent_report

Absentees for a date

late_report

Late / leave / absent over a range

mobile_punch_report

App/selfie punches over a range

leave_balance_report

Leave balances

applied_leave_list

Leave applications (view only)

monthly_overtime_report

Overtime report

list_workplaces

Offices/locations

list_departments

Departments

list_designations

Job titles

list_holidays

Holidays

list_notifications

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 .env

Edit .env:

TIPSOI_EMAIL=service-account@yourcompany.com
TIPSOI_PASSWORD=...
TIPSOI_OFFICE_ID=4397        # optional default; discover via list_workplaces
TIPSOI_COMPANY_ID=4146       # optional default

Use 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.server

It 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.server

Call 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.

  1. Open Claude Desktop → Settings → Developer → Edit Config (this opens claude_desktop_config.json).

  2. 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.

  1. 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.

  1. 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.

  1. In Claude: Settings → Connectors → Add custom connector, then paste the public URL, e.g. https://tipsoi-mcp.yourcompany.com/mcp.

  2. 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 (or year/month); the server converts to Tipsoi's epoch-millisecond format using Asia/Dhaka (UTC+6). Override with TIPSOI_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 tools
applied_leave_listA
Read-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_reportA
Read-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_summaryB
Read-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_employeeA
Read-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_reportA
Read-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_reportB
Read-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_departmentsC
Read-only

List departments.

Args: include_inactive: Include inactive departments. Default True.

Inputs: include_inactive.

list_designationsA
Read-only

List all designations (job titles).

Inputs: no named parameters.

list_employeesA
Read-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_holidaysA
Read-only

List configured holidays.

Inputs: no named parameters.

list_notificationsA
Read-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_workplacesA
Read-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_reportA
Read-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_attendanceA
Read-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_reportC
Read-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

    A3.5/5.0

    Scored across 15 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Read-only MCP server for the Humaans HRIS API, providing tools to query people, reporting chains, compensation, time away, and more.
      33
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP 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.
      33
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A 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 npm
      3
      MIT