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., "@mcp-beebole show me my active projects"
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.
This Model Context Protocol (MCP) server allows AI assistants to interact with the Beebole REST API for time tracking management.
Enable an AI assistant to list your active projects, view your time entries, and log work hours or absences.
Related MCP server: EARLY App MCP Server
Node.js (TypeScript)
@modelcontextprotocol/sdk
axios for HTTP requests.
zod for schema validation.
Clone this repository.
Install dependencies:
npm installBuild the project:
npm run buildAuthentication relies on a personal Beebole API token.
BEEBOLE_API_TOKEN: Your API token that you can retrieve from Beebole using the API Token module on your home screen.
Add the following configuration to your claude_desktop_config.json file (typically located at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"beebole": {
"command": "node",
"args": ["/path/to/mcp-beebole/build/index.js"],
"env": {
"BEEBOLE_API_TOKEN": "YOUR_API_TOKEN"
}
}
}
}There are two ways to use Beebole with Gemini CLI:
This is the easiest way. It includes the MCP server and a specialized @beebole subagent.
Download: Get beebole-extension.zip from the latest GitHub release.
Extract: Unzip the archive to a directory of your choice.
Link: Run the following command inside the extracted directory:
gemini extensions link .Configure: Run gemini settings to enter your BEEBOLE_API_TOKEN.
If you prefer to add the MCP server manually to your workspace:
gemini mcp add beebole node /path/to/mcp-beebole/build/index.js -e BEEBOLE_API_TOKEN=$BEEBOLE_API_TOKENHere are some ways you can interact with Beebole through your AI assistant:
Prompt: "What are my active projects in Beebole?"
Assistant Action: Calls list_my_projects.
Result: Displays a list of projects, subprojects, and tasks with their respective IDs.
Prompt: "Log 7.5 hours on the 'Development' project for today with the comment 'Working on the MCP server'."
Assistant Action:
Calls list_my_projects to find the ID for "Development".
Calls create_time_entry with today's date, the resolved project ID, 7.5 hours, and the provided comment.
Result: Confirmation that the entry was created or updated in Beebole.
Prompt: "Show me my time entries for this week."
Assistant Action: Calculates the dates for the current week and calls get_time_entries.
Result: A summary table of all hours logged for each day of the week.
list_my_projects
Description: Returns a list of the user's active projects and tasks.
create_time_entry
Parameters:
date: Date (format YYYY-MM-DD).
project_id: ID of the project or task.
hours: Number of hours (numeric).
comment: (Optional) Comment.
Description: Creates a new time entry.
get_time_entries
Parameters:
start_date: Start date (YYYY-MM-DD).
end_date: End date (YYYY-MM-DD).
Description: Lists existing time entries for the given period.
The project uses vitest for unit tests:
npm testEnsure your BEEBOLE_API_TOKEN is correct. You can find it in Beebole > Settings > Account.
If the assistant cannot find a project, try calling list_my_projects first. Only active projects and tasks are returned by the API.
Check the logs in Claude Desktop (often located in ~/Library/Logs/Claude/mcp.log on macOS).
Ensure node is in your system PATH and accessible by the Claude app.
Make sure you ran npm run build to generate the build/ folder.
This project is licensed under the MIT License. See the LICENSE file for details.
Create or update a time entry in Beebole. You MUST provide either project_id OR absence_id, but NOT both.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date (YYYY-MM-DD) | |
| hours | Yes | Number of hours | |
| comment | No | Optional comment | |
| task_id | No | Optional ID of the task (Only used with project_id) | |
| absence_id | No | ID of the absence type (Mutually exclusive with project_id) | |
| project_id | No | ID of the project/subproject/company (Mutually exclusive with absence_id) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses the create/update nature and the mandatory parameter constraint, though it does not elaborate on update semantics or return values.
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 the action, no redundant language. Every word 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 6-param tool with no output schema, the description covers the essential usage rule and action, but could mention outcomes (e.g., what an update does to existing entries) or return values. Still, it is largely sufficient for basic use.
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 well-documented. The description adds the 'must provide one' rule beyond the schema's mutual-exclusivity notes, providing valuable parameter guidance.
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 'Create or update a time entry in Beebole' with a specific verb and resource, and adds the key mutual-exclusivity constraint that distinguishes it from sibling list/get tools.
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?
The description gives explicit context for when to use the tool (creating/updating time entries) and a critical usage rule (must provide either project_id or absence_id), but it does not explicitly mention alternatives like get_time_entries for viewing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get time entries for a given period.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | Yes | End date (YYYY-MM-DD) | |
| start_date | Yes | Start date (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It indicates a read operation ('Get') but omits important context such as whether entries are scoped to the authenticated user or all users, whether the date range is inclusive, and any potential pagination or ordering behavior. This leaves significant ambiguity for an agent.
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?
The description is a single sentence of eight words, front-loaded with the action and resource. There is no redundant or filler content; every word serves a purpose.
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?
This is a simple read tool with two well-described parameters and no output schema. The description is minimally sufficient but leaves gaps: it does not clarify the scope of time entries (e.g., user-specific vs. all users) or hint at the response format. Given the absence of annotations and output schema, the description could be more complete, but it remains viable for an agent to select and invoke correctly with the information present.
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 description coverage is 100% (both start_date and end_date have format descriptions). The tool description adds the concept of a 'period', which slightly clarifies the relationship between the two parameters, but it does not add substantive meaning beyond the schema. Baseline of 3 is appropriate.
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 uses a specific verb ('Get') and resource ('time entries') with a scope ('for a given period'). This clearly distinguishes it from sibling tools like list_my_projects and create_time_entry, which have different resources or actions.
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?
The description implies usage for retrieving time entries within a date range, which is clear from the parameter requirement. However, it does not explicitly state when to use this tool versus alternatives like create_time_entry, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available absence types (Vacation, Sick Leave, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the primary action (listing) but does not mention potential aspects such as authentication requirements, whether all absence types are always returned, or what the return format looks like. This is acceptable for a simple read-only tool but lacks depth beyond the core behavior.
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?
The description is a single, concise sentence that is front-loaded with the action and resource. It contains no superfluous words and is easily scannable, making it appropriately sized for a simple tool.
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?
Considering the low complexity of the tool (no parameters, no annotations, no output schema), the description is largely complete. It covers the main purpose and gives examples. A slight gap is that it does not specify what information is returned for each absence type, but for a simple listing this is not critical, so a high score is justified.
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?
The input schema has zero parameters, so the baseline for parameter semantics is 4. The description does not need to explain any parameters, and it adds context by providing example values, though those are not directly related to parameter semantics. This is sufficient given the absence of parameters.
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 the tool's function with a specific verb 'List' and a specific resource 'absence types', including examples ('Vacation, Sick Leave, etc.'). This distinguishes it from sibling tools that handle projects and time entries, making the purpose unambiguous.
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?
The description implicitly defines when to use the tool: whenever a list of available absence types is needed. Although it does not explicitly mention alternatives, the sibling tools are clearly different (projects, time entries), so there is no real ambiguity. However, it lacks explicit 'when not to use' guidance, so a perfect score is not warranted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active projects and tasks where time can be logged.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It adds two meaningful qualifiers ('active' and 'where time can be logged'), which go beyond a simple 'list projects'. However, it does not disclose return format, pagination, or any other behavioral traits, leaving some gaps.
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?
The description is a single sentence of 9 words, front-loaded with the verb and resource. Every word earns its place, and there is no redundancy or irrelevant 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?
Given the tool's simplicity (no parameters, no output schema), the description adequately explains its purpose and scope. It could potentially mention pagination or the relationship between projects and tasks, but these are not essential for a basic list tool.
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?
The tool has zero parameters, so the schema provides no information. The baseline for 0 params is 4, and the description does not need to compensate for missing parameter details. It clearly explains what the tool returns, which is sufficient.
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 uses a specific verb ('List') and a clear resource ('active projects and tasks') with a specific purpose ('where time can be logged'). It distinguishes itself from siblings like list_absence_types (absence types) and get_time_entries (time entries) by scoping to projects/tasks eligible for time logging.
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?
The description implies clear usage context: when you need to see available projects/tasks for logging time. It doesn't explicitly mention when not to use it or alternative tools, but the context is evident from the phrasing and sibling names.
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.
v1.1.0create_time_entryget_time_entrieslist_absence_typeslist_my_projectsScored across 4 tools
Each tool has a clear, distinct purpose: listing projects, listing absence types, creating/updating time entries, and retrieving time entries. There is no overlap or ambiguity between them.
All tools follow the verb_noun pattern (list_*, create_*, get_*) and use snake_case consistently. The inclusion of 'my' in list_my_projects is a minor deviation but does not break the overall consistency.
Four tools is a well-scoped set for a time-tracking integration, covering the essential operations without being overly sparse or bloated.
The set covers the core lifecycle: listing the targets for time entries (projects and absence types), creating/updating entries, and retrieving entries. A delete operation is missing, but this is a minor gap that can be worked around.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server providing attendance data queries via the CloudTime API.
