ehour-mcp

An MCP server that fills and saves eHour timesheets for you. Ask your agent "submit my June hours": it drafts each day from your git log, shows you the month, and after your OK fills the timesheet in a real Chrome window, saves it week by week and reads it back to check.

• Drafts from commits. PROJ-123 Title - detail subjects become one entry per weekday; weekend commits move to the nearest free weekday.

• Review before anything is saved. The draft is a JSON file the agent shows and edits with you.

• Verified saves. Every week is read back after saving and compared with what you approved.

• Small fixes. patch_day corrects one day without touching the rest.

• No stored credentials. It attaches over the Chrome DevTools Protocol to a Chrome window where you logged in yourself.

See docs/DESIGN.md for how it works and what it refuses to do.

Requirements

• Node.js 20 or newer

• Google Chrome (any Chromium-based browser works via cdpBrowser)

• An eHour account with one project row on your timesheet

• An MCP client such as Claude Code

Related MCP server: Timesheet Assistant MCP

Setup

1. Install dependencies:

   npm install

2. Create your config from the example and fill it in:

   cp ehour.config.example.json ehour.config.json

   Key	Required	Meaning
   url	yes	Your eHour timesheet page, e.g. https://ehour.example.com/eh/consultant/overview?1&openPanel=TIMESHEET
   projectCode	yes	The project code shown on your timesheet row, e.g. PROJ
   ticketPrefixes	no	Ticket keys to recognise in commit subjects, e.g. ["PROJ", "OPS"]. Default: any UPPERCASE-123 key
   gitRepo	no	Repository draft_month reads by default
   cdpPort	no	Chrome remote-debugging port, default 9237
   cdpProfile	no	Chrome profile folder, default ~/.ehour-cdp-profile
   cdpBrowser	no	Browser binary, default Google Chrome on macOS
   host	no	Host used to find the eHour tab, default taken from url

   Every key can also be set as an environment variable (EHOUR_URL, EHOUR_PROJECT_CODE, EHOUR_TICKET_PREFIXES as a comma list, EHOUR_GIT_REPO, EHOUR_CDP_PORT, …), which wins over the file. EHOUR_CONFIG points to a different config file.

3. Start the dedicated Chrome and sign in to eHour once:

   ./scripts/start-ehour-chrome.sh

   It uses its own profile, so your normal browsing is untouched and the session survives restarts.

4. Register the server with your MCP client. For Claude Code:

   claude mcp add ehour -- node /absolute/path/to/ehour-mcp/src/server.mjs

Use

• "Submit my June hours" → draft_month writes drafts/<from>_<to>.json from your commits and returns a summary. The agent shortens each day, fills the gaps, shows you the month, and on your OK calls apply_month with that file.

• "June 3 should say X" → patch_day.

• "What's in eHour for last week?" → read_timesheet.

Notes

• The server never closes Chrome. Quit it with ./scripts/stop-ehour-chrome.sh.

• If the session expires, check_login says so: sign in again in that window.

• Every day gets 8 hours unless an entry says otherwise. Comments are converted to ASCII because eHour stores them in CP-1252.

• Tested against one eHour installation with the standard web UI. A customised skin may need the selectors in src/ehour-dom.mjs adjusted.

Development

npm test        # unit tests: entries, week math, drafting, config
npm run smoke   # read-only checks against your live eHour: page | login | read FROM TO

License

MIT