使用说明

MCP Woffu Server

A Model Context Protocol (MCP) server for Woffu time tracking integration. This server allows AI assistants like Claude to interact with your Woffu account for clock-in/out operations and time tracking management.

Features

Clock In/Out: Start and end your workday with simple commands
Today's Status: Check your current work status, hours worked, and schedule
Week/Month Summary: Get a comprehensive overview of your worked hours
Complete Past Days: Fill in missing time entries for past dates
Pending Days: View days without logged hours
Confirm Days: Confirm (accept) workday diaries

Installation

Using npx from GitHub (recommended)

npx github:iflorit/mcp-woffu-server

Installing globally from GitHub

npm install -g github:iflorit/mcp-woffu-server
mcp-woffu-server

From source

git clone https://github.com/iflorit/mcp-woffu-server.git
cd mcp-woffu-server
npm install
npm run build

Configuration

The server requires the following environment variables:

Variable	Description	Required
`WOFFU_TOKEN`	JWT Bearer token for Woffu API	Yes
`WOFFU_USER_ID`	Your Woffu user ID	Yes
`WOFFU_BASE_URL`	Woffu instance URL (e.g., `https://mycompany.woffu.com`)	No (defaults to `https://app.woffu.com`)

How to get your Woffu JWT Token

Log in to your Woffu web portal (e.g., https://mycompany.woffu.com)
Open browser Developer Tools (F12)
Go to the Application tab (Chrome) or Storage tab (Firefox)
In the left panel, expand Cookies
Click on your Woffu domain (e.g., https://mycompany.woffu.com)
Find the cookie named woffu.token
Copy the value - this is your WOFFU_TOKEN

Alternative via Console:

document.cookie.split(';').find(c => c.trim().startsWith('woffu.token=')).split('=')[1]

Note: JWT tokens expire periodically. You may need to refresh the token when it expires.

How to find your User ID

The User ID is embedded in the JWT token. You can decode it at jwt.io and look for the UserId field in the payload.

Alternatively:

In the browser Developer Tools, go to Network tab
Perform any action in Woffu
Look at any API request URL - it often contains your user ID (e.g., /api/users/1234567/...)

Usage

With Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "woffu": {
      "command": "npx",
      "args": ["-y", "github:iflorit/mcp-woffu-server"],
      "env": {
        "WOFFU_TOKEN": "your-jwt-token-here",
        "WOFFU_USER_ID": "your-user-id",
        "WOFFU_BASE_URL": "https://mycompany.woffu.com"
      }
    }
  }
}

With Claude Code

claude mcp add woffu --env WOFFU_TOKEN=your-token --env WOFFU_USER_ID=your-id --env WOFFU_BASE_URL=https://mycompany.woffu.com -- npx -y github:iflorit/mcp-woffu-server

Or add to your .claude.json:

{
  "mcpServers": {
    "woffu": {
      "command": "npx",
      "args": ["-y", "github:iflorit/mcp-woffu-server"],
      "env": {
        "WOFFU_TOKEN": "your-jwt-token-here",
        "WOFFU_USER_ID": "your-user-id",
        "WOFFU_BASE_URL": "https://mycompany.woffu.com"
      }
    }
  }
}

Running the Server Directly

# With environment variables
export WOFFU_TOKEN="your-token"
export WOFFU_USER_ID="your-user-id"
export WOFFU_BASE_URL="https://mycompany.woffu.com"

# Run the server
npx github:iflorit/mcp-woffu-server

Available Tools

`woffu_clock_in`

Clock in to start your workday.

Parameters: None

Example response:

{
  "status": "success",
  "action": "clock_in",
  "timestamp": "2024-01-15T09:00:00",
  "signEventId": "12345"
}

`woffu_clock_out`

Clock out to end your workday.

Parameters: None

Example response:

{
  "status": "success",
  "action": "clock_out",
  "timestamp": "2024-01-15T18:00:00",
  "signEventId": "12346"
}

`woffu_status`

Get today's work status including schedule and hours worked.

Parameters: None

Returns: Detailed workday information including:

Current clock status
Hours worked today
Expected hours
Break times

`woffu_month_summary`

Get a summary of worked hours for a specific month.

Parameters:

year (optional): Year (defaults to current year)
month (optional): Month 1-12 (defaults to current month)

Returns: Monthly presence summary with daily breakdowns.

`woffu_week_summary`

Get a weekly summary of worked hours.

Parameters:

date (optional): Any date within the desired week in YYYY-MM-DD format

Returns: Weekly presence summary with daily breakdowns.

`woffu_day_detail`

Get detailed information for a specific day.

Parameters:

date (optional): Date in YYYY-MM-DD format (defaults to today)

Returns: Detailed day information including all clock events.

`woffu_pending_days`

Get days without completed hours.

Parameters:

year (optional): Year (defaults to current year)
month (optional): Month 1-12 (defaults to current month)

Returns: List of workdays where no hours have been logged.

`woffu_schedule`

Get the user's assigned work schedule.

Parameters: None

Returns: Schedule information including work hours and office details.

`woffu_complete_day`

Edit time entries for a past day (at most 2 slots).

Woffu's slot endpoint can only edit signs that already exist: on a day with no clock in/out it answers 204 but persists nothing. The tool refuses to write at all unless the requested slots cover the day's scheduled hours (e.g. 8h) in at most 2 slots and the day already has persisted signs to edit. It then re-reads the persisted signs after writing and returns an error unless they cover the day's scheduled hours in at most 2 slots (verified carries the detail). Days with no signs must get their clock in/out created first (web or woffu_clock_in/woffu_clock_out).

When slots is omitted the tool targets a single block: the schedule's start time plus its working time (e.g. 08:00-16:00 for an 8h day, 09:00-15:00 for a 6h Friday). Surplus signs cannot be deleted through the API, so they are collapsed onto the block end as zero-length pairs; those pairs count neither as hours nor as slots. Woffu rejects (400 _SignAddError) sign times in the future, so today can only be filled once the block has ended.

Parameters:

date: Date in YYYY-MM-DD format
slots: List of up to 2 time slots with in_time and out_time (HH:MM format)
confirm (optional, default false): confirm (accept) the day right after filling it. Only happens when the verification above passes.
force (optional, default false): fill even if the day is a weekend, holiday, calendar event, or has absences/vacations (refused otherwise)

Example:

{
  "date": "2024-01-10",
  "slots": [
    {"in_time": "09:00", "out_time": "14:00"},
    {"in_time": "15:00", "out_time": "18:00"}
  ]
}

`woffu_confirm_day`

Confirm (accept) one or more workday diaries, marking the day's records as reviewed by the employee. Already-confirmed days are skipped.

Refuses days whose persisted signs don't cover the scheduled hours (e.g. 8h) or aren't compacted into at most 2 slots, unless force: true. The response lists the reasons per date under not_ready.

Parameters:

dates: List of dates in YYYY-MM-DD format
force (optional, default false): confirm even if the day is incomplete

Example:

{
  "dates": ["2024-01-10", "2024-01-11"]
}

`woffu_unconfirm_day`

Unconfirm (revert acceptance of) one or more workday diaries, unlocking them for editing again. Confirmed days are locked: woffu_complete_day refuses them until unconfirmed.

Parameters:

dates: List of dates in YYYY-MM-DD format

Example Conversations with Claude

"Clock me in to Woffu"

"What's my work status for today?"

"Show me my hours for November 2024"

"I forgot to clock in yesterday. Can you fill in 9:00-14:00 and 15:00-18:00 for 2024-01-14?"

"Show me my pending days this month"

Development

Setup

git clone https://github.com/iflorit/mcp-woffu-server.git
cd mcp-woffu-server
npm install

Building

npm run build

Running in development

npm run dev

Tests

npm test        # TypeScript guard tests + Python example tests

Unattended agent example

examples/pi-agent/ is a cron-driven Python script (no LLM, no dependencies) that keeps every workday signed as one block of the scheduled hours and confirms it only when the hours match. It encodes the API constraints documented above and ships with its own unit tests.

Security Notes

Never commit your JWT token to version control
Use environment variables or secure secret management
JWT tokens expire - refresh the token from the woffu.token cookie when needed
The server only accepts local connections by default

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with the Model Context Protocol SDK
Integrates with Woffu time tracking

使用说明

MCP Woffu Server

Features

Installation

Using npx from GitHub (recommended)

Installing globally from GitHub

From source

Configuration

How to get your Woffu JWT Token

How to find your User ID

Usage

With Claude Desktop

With Claude Code

Running the Server Directly

Available Tools

woffu_clock_in

woffu_clock_out

woffu_status

woffu_month_summary

woffu_week_summary

woffu_day_detail

woffu_pending_days

woffu_schedule

woffu_complete_day

woffu_confirm_day

woffu_unconfirm_day

Example Conversations with Claude

Development

Setup

Building

Running in development

Tests

Unattended agent example

Security Notes

License

Contributing

Acknowledgments

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器

`woffu_clock_in`

`woffu_clock_out`

`woffu_status`

`woffu_month_summary`

`woffu_week_summary`

`woffu_day_detail`

`woffu_pending_days`

`woffu_schedule`

`woffu_complete_day`

`woffu_confirm_day`

`woffu_unconfirm_day`