This MCP server provides authenticated, read/write access to easyJOB timesheets and job data, with a strong emphasis on safe time tracking.
Authentication: Automatically handles OAuth token fetching and refresh.
Time Tracking: Book hours with track_time (supporting duration or start/end time, optional activity, date, work type, description), preview and batch import via track_time_batch, and correct your own entries with update_time_record.
Job & Activity Lookup: Find jobs (search_jobs), get details (get_job_details), list activities/positions (list_job_activities), and review budgets (job_budget_report).
Reports: Generate timesheet summaries (timesheet_report), team hours (team_hours_report), absence lists (list_absences), and recorded time lists (list_time_records).
User Info: Retrieve your internal user ID (get_user_id) and access the user profile resource.
Generic Queries: Run arbitrary FetchsonQuery reads against any entity with query_entities (filtering, sorting, field selection).
Conditional Generic Writes: Create, update (create_or_update_entity), or delete (delete_entity) any easyJOB entity – these are disabled by default and require setting EASYJOB_ENABLE_GENERIC_WRITES=1. The update tool explicitly blocks manipulation of TimeRecording entities for safety.
Safety Constraints: Time writes are restricted to your own timesheet; batch operations default to dry-run; duplicate time entries are blocked unless explicitly allowed; generic write tools are hidden unless opted in.
Integration: Includes a CLI (easyjob-sync) to push tracked time from Super Productivity into easyJOB, and is configurable via environment variables for use with clients like Claude Desktop.
Click on "Install 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., "@easyJOB MCP Server Search for a job named 'Website Redesign'"
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.
A clean, stable, and highly configurable Model Context Protocol (MCP) server for the easyJOB REST API.
This server manages dynamic OAuth authentication token fetching and caching, simplifies complex multi-query workflows (such as looking up user and job IDs to record time), and provides full read/write access to easyJOB via generic endpoints.
This server is normally pointed at a production easyJOB instance holding real agency data, so it is deliberately narrow in what it can change:
The only writes it performs are time recordings: booking hours and correcting your own entries. Nothing else is created, restructured or deleted.
update_time_record verifies ownership against EASYJOB_USERNAME and refuses to
touch anyone else's timesheet. The API token itself can write other people's
records, so this guard lives in the server rather than in the caller.
track_time_batch defaults to a dry run: it validates and returns a preview
without writing. A batch is applied all-or-nothing, so it never lands half-done.
Identical entries on the same day for the same job are refused as duplicates
unless allow_duplicate is set explicitly.
The generic create_or_update_entity and delete_entity tools can touch any
record, so they are hidden and blocked unless you set
EASYJOB_ENABLE_GENERIC_WRITES=1. Everything above works without them.
Query failures are detected properly: easyJOB signals them with HTTP 200, either
as an error envelope or as an empty body (see API-NOTES.md), which previously
could turn a typo into a silently empty report.
Related MCP server: OAuth MCP Server
Automated token management — fetches and caches the OAuth bearer token, retries transient network failures, and refreshes automatically when the API rejects a token.
Tool | Purpose |
| Find jobs by number, name, short name or customer; shows whether each accepts bookings |
| Complete job context in one call: header, customer, positions and hours booked per position |
| Positions (Leistungen) with budget, booked and remaining hours — how you pick a valid |
| Budget vs. actual per position, remaining budget, burn rate, hours per contributor |
| The individual records booked in a date range |
| Totals grouped by day, job, activity or customer, plus working days with no bookings |
| Hours per employee, optionally against recorded attendance (Arbeitszeit) |
| Who is absent in a range, with type and days |
| Internal user ID of the configured login |
| Escape hatch for arbitrary |
Tool | Purpose |
| Book hours on one job, with validation and duplicate protection |
| Validate and preview several entries, then book them after confirmation |
| Correct one of your own records (hours, description, date, times, position) |
Budgets are read from each position's EstimateQuantity. Quantities in hours
(Std., h) are used directly, quantities in days (Tag(e), Tage, AT) are
converted at EASYJOB_HOURS_PER_DAY (default 8). Units such as pauschal,
Stck. or Monat(e) are not time budgets and are reported as budgetHours: null
alongside their raw quantity.
easyjob-sync — booking Super Productivity time into easyJOBSuper Productivity (MIT,
macOS/Windows/Linux) serves as the local tracker. Its Local REST API only listens on
127.0.0.1, so the bridge is a CLI that runs on your own machine — the
containerised MCP server cannot reach it. Both share the same easyJOB client.
In Super Productivity: Settings → Misc → "Enable local REST API".
List what the tracker knows and map each project to an easyJOB job and position:
node --env-file=.env bin/easyjob-sync.js status
node --env-file=.env bin/easyjob-sync.js projects
node --env-file=.env bin/easyjob-sync.js map <spProjectId> --job UNI_2604_131 --activity 43966
node --env-file=.env bin/easyjob-sync.js map-tag <spTagId> --activity 43969 # tag overrides the position
node --env-file=.env bin/easyjob-sync.js map <spProjectId> --ignore # never book this projectThe mapping lives in ~/.config/easyjob-sync/config.json (override with
EASYJOB_SYNC_CONFIG). Super Productivity has no field for foreign keys, which is
why the mapping is kept here rather than in the tracker.
node --env-file=.env bin/easyjob-sync.js preview --from 2026-07-01 --to 2026-07-31
node --env-file=.env bin/easyjob-sync.js push --from 2026-07-01 --to 2026-07-31 --yespreview never writes. push refuses to write without --yes, validates every
target job and position first, and aborts before writing anything if one is invalid.
Time comes from each task's timeSpentOnDay, the finest granularity the tracker
stores. Entries are grouped per day + job + position, so one day on one
position becomes exactly one easyJOB record, with the task titles as description.
Rounding happens once per group (default 15 minutes, roundToMinutes), never
per task, so several small tasks cannot inflate a day. The preview shows both the
rounded and the exact figure.
Task-days below minMinutes (default 5) are dropped as tracking noise and listed
as skipped.
Re-running is safe. Each record carries
ExternalReference = sp:<date>:<jobId>:<activityId> plus
ThirdPartyApp = super-productivity, and existing references are recognised and
skipped rather than booked twice.
Projects without a mapping are never booked; they are reported with their hours so you can decide.
Super Productivity does not document whether its API reports milliseconds or
seconds, and being wrong by a factor of 1000 would book nonsense. The unit is
therefore derived from the data (a single day cannot exceed 86400 seconds, and the
app ticks in whole seconds). If the range is too small to tell, the tool stops
and asks you to set timeUnit to "ms" or "s" in the config rather than guessing.
The detected unit and the reason are printed on every run.
Run the following command inside this directory to install the @modelcontextprotocol/sdk:
npm installThe server reads its configuration from environment variables. You can set these in your terminal, a .env file (if running locally/testing), or directly in your MCP client's configuration (e.g., Claude Desktop).
Environment Variable | Description |
| Required. The absolute URL to the easyJOB app (e.g., |
| The easyJOB login name (used for password grant token lookup & user ID resolution). |
| The easyJOB password (used for password grant token lookup). |
| OAuth Client ID (if using client credentials flow or required for password flow). |
| OAuth Client Secret (if using client credentials flow). |
| Optional. Custom OAuth Token URL (defaults to |
| Optional. A static, long-lived bearer token (bypasses automatic auth flows). |
| Optional. Factor for converting day-based position budgets into hours (default |
| Optional. Set to |
To configure the server in Claude Desktop, edit your claude_desktop_config.json configuration file:
On Linux/macOS:
~/.config/Claude/claude_desktop_config.json or ~/Library/Application Support/Claude/claude_desktop_config.json
Add the server config:
{
"mcpServers": {
"easyjob": {
"command": "node",
"args": ["/absolute/path/to/jolly-hypatia/index.js"],
"env": {
"EASYJOB_API_BASE_URL": "https://drid.because.cloud/drid/app",
"EASYJOB_USERNAME": "your_username",
"EASYJOB_PASSWORD": "your_password",
"EASYJOB_CLIENT_ID": "optional_client_id",
"EASYJOB_CLIENT_SECRET": "optional_client_secret"
}
}
}
}Restart Claude Desktop after editing the configuration.
get_user_idDescription: Get the internal easyJOB User ID for the user configured in the environment (EASYJOB_USERNAME).
Arguments: None. (Resolves strictly to the authenticated user context for security).
search_jobsDescription: Search for jobs by name, short name, or job number.
Arguments:
query (string, required): Wildcard search term.
track_timeDescription: Log working hours on a specific job in easyJOB. Creates a TimeRecording entry strictly for the configured user timesheet.
Arguments:
job_id (integer, required): Internal ID of the Job.
amount (number, required): Time in hours (e.g., 1.5 or 0.25).
description (string, required): Work description.
date (string, optional): Date in YYYY-MM-DD format (defaults to today).
time_recording_type_id (integer, optional): Custom work type ID (from Activity/Leistung table).
query_entitiesDescription: Run a custom FetchsonQuery.
Arguments:
query (object, required): A FetchsonQuery JSON definition.
create_or_update_entityDescription: Create or update any entity in easyJOB.
Arguments:
entity (string, required): Entity name (e.g., 'Task').
data (object, required): Entity fields and values.
Note: Creating or updating TimeRecording entities via this tool is disabled for security. Use track_time instead.
delete_entityDescription: Delete an entity by ID.
Arguments:
entity (string, required): Entity name.
id (integer, required): Target entity ID.
import-hoursDescription: A guided prompt template to help the AI dry-run map, verify, and import a batch of working hours (timesheet) into easyJOB.
Arguments:
hoursList (string, required): The list or table of working hours to log.
easyjob://docs/skillDescription: The complete integration guide and safety protocols (content of SKILL.md) read dynamically from disk.
easyjob://user/profileDescription: Dynamically retrieves the profile, department details, and status of the currently authenticated user from the easyJOB database.
Generic tool to create or update any entity (e.g. TimeRecording, Task) in easyJOB.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | The payload representing the entity fields and values. | |
| entity | Yes | Name of the entity (e.g., 'TimeRecording', 'Task'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'create or update' but lacks details on upsert behavior, authentication, or side effects. For a mutation tool with zero annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no filler. Front-loaded with action and scope. Could benefit from more structure but remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, nested object parameter without structure guidance, no return value or error description. Generic tool with many unknowns, incomplete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds no extra meaning beyond schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it creates or updates any entity, with examples like TimeRecording and Task. Distinguishes from siblings (delete, query, search, track) by covering the create/update use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: use for creating/updating entities as opposed to delete or query. No explicit when-to-use or when-not-to-use guidance, nor alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an entity in easyJOB by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the entity to delete. | |
| entity | Yes | Name of the entity type (e.g., 'TimeRecording'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether deletion is permanent, irreversible, or requires confirmation. Lacks essential context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, direct and to the point. Could benefit from slightly more context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal description for a deletion tool with no output schema and no annotations. Does not explain return values, side effects, or preconditions. Incomplete for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameter descriptions in the schema are adequate. The tool description repeats 'by ID' but adds no new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete), the resource (entity in easyJOB), and the method (by ID). Distinguishes from siblings like create_or_update_entity and query_entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the internal easyJOB User ID for the configured user (EASYJOB_USERNAME). The User ID is required to track hours.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Discloses use of EASYJOB_USERNAME environment variable but does not detail behavior (e.g., caching, error handling, network call). Adequate for a simple getter but lacking depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loading purpose and context. No superfluous information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool without output schema, description is sufficient. Identifies what is retrieved and its necessity for time tracking. Could mention return type but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters, but description adds value by specifying the configured user comes from EASYJOB_USERNAME. This clarifies implicit source. With 100% schema coverage, description enhances meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets the internal easyJOB User ID for the configured user. Verb 'Get' and resource 'internal easyJOB User ID' are specific. Distinguishes from sibling tools like track_time which requires this ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions the User ID is required to track hours, implying use before track_time. Does not explicitly state when not to use or alternatives, but clear enough for a simple utility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a generic FetchsonQuery against any easyJOB entity. Allows filtering and custom selections on User, Job, TimeRecording, Task, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The FetchsonQuery configuration object. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full responsibility. It calls the query 'generic' but doesn't explain behavior like read-only nature, pagination, performance impact, or security needs. Insufficient disclosure for a potentially heavy query.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and scope. No filler words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no explanation of response format, error cases, or typical use. The description is too brief for a complex query tool with a nested input object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully documented in the schema. Description adds context about entity types but no additional semantics beyond schema. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Execute a generic FetchsonQuery' and the resource 'any easyJOB entity', listing examples like User, Job, TimeRecording. Distinguishes well from sibling tools like create_or_update_entity and delete_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly suggests use for querying/reading data but lacks explicit when-to-use vs. siblings, no exclusions or alternative recommendations. Middle score due to absence of guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for jobs in easyJOB by Name, ShortName, or JobNo. Returns matching jobs with their IDs. Always run this to find the correct JobId before logging time.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term matching the job's Name, ShortName, or JobNo (wildcard like search). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies read-only but does not explicitly state safety. Lacks details on result limits or pagination. Adequate but could be improved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: action, return, usage. No fluff, front-loaded, and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter search tool without output schema, description covers purpose, return, and usage context. Missing details on result set size but sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already has description with wildcard mention. Description adds that query matches Name, ShortName, or JobNo, which provides useful context but is not extensive. Schema coverage 100% sets baseline at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches for jobs by Name, ShortName, or JobNo and returns IDs. Distinguishes from siblings like query_entities by being job-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use this before logging time, linking to track_time sibling. Provides clear workflow context but no when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log working hours on a specific job in easyJOB. Creates a TimeRecording entry for the configured user. Supports duration (amount) OR start/end times (from_time/to_time).
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Optional date for the entry in YYYY-MM-DD format. Defaults to today. | |
| amount | No | The duration of time in hours (e.g., 1.5 for 1h 30m). Optional if from_time and to_time are provided. | |
| job_id | Yes | The internal ID of the Job. | |
| to_time | No | Optional ending time in HH:MM format (e.g., '15:45'). | |
| from_time | No | Optional starting time in HH:MM format (e.g., '13:00'). | |
| product_id | No | Optional internal ProductId. | |
| activity_id | No | Optional internal ID of the Activity (Leistung) associated with the job (e.g., 32004). | |
| customer_id | No | Optional internal CustomerId. Usually resolved automatically from the JobId. | |
| description | Yes | Details of what was worked on. | |
| time_recording_type_id | No | Optional internal TimeRecordingTypeId (type of work). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions creating an entry and supports duration or start/end times, but omits critical behavioral info like authentication requirements, idempotency, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences that front-load the main action and add key details about parameter usage. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description covers the primary function and key parameter constraint, but lacks details on return values, error handling, and prerequisites. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by specifying mutual exclusivity of amount vs from_time/to_time, which is not in individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it logs working hours on a specific job in easyJOB and creates a TimeRecording entry. It distinguishes from sibling tools which are general CRUD or search operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for logging time on jobs, but does not explicitly state when not to use or alternatives. Sibling tools are for different purposes, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0create_or_update_entitydelete_entityget_user_idquery_entitiessearch_jobstrack_timeMost tools have distinct purposes (track_time vs. generic CRUD, search_jobs, etc.), but the generic create_or_update_entity could cause slight confusion when a specialized tool like track_time exists for similar entities.
All tool names follow a consistent verb_noun pattern using lowercase snake_case, e.g., create_or_update_entity, delete_entity, query_entities, search_jobs, track_time.
Six tools cover the core domain (job management, time tracking) without being excessive or insufficient; each tool serves a clear purpose.
Generic CRUD tools cover basic operations but lack specialized tools for updating jobs or managing users; the set works but has notable gaps for a full workflow.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that provides access to Testiny projects, test cases and test runs
Public MCP server for discovering open jobs. Search, filter, and get application links.
MCP Server for JFrog, providing tools for development and artifact management.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/chrustek-studio/easyjob-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
