mcp-beebole
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.
MCP Beebole
This Model Context Protocol (MCP) server allows AI assistants to interact with the Beebole REST API for time tracking management.
Purpose
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
Technical Stack
Node.js (TypeScript)
@modelcontextprotocol/sdkaxiosfor HTTP requests.zodfor schema validation.
Installation
Clone this repository.
Install dependencies:
npm installBuild the project:
npm run build
Configuration (Environment Variables)
Authentication 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.
Usage with Claude Desktop
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"
}
}
}
}Usage with Gemini CLI
There are two ways to use Beebole with Gemini CLI:
Option 1: Gemini CLI Extension (Recommended)
This is the easiest way. It includes the MCP server and a specialized @beebole subagent.
Download: Get
beebole-extension.zipfrom 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 settingsto enter yourBEEBOLE_API_TOKEN.
Option 2: Standalone MCP Server
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_TOKENUsage with Claude Desktop
Here are some ways you can interact with Beebole through your AI assistant:
1. Discovering your projects
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.
2. Logging time
Prompt: "Log 7.5 hours on the 'Development' project for today with the comment 'Working on the MCP server'."
Assistant Action:
Calls
list_my_projectsto find the ID for "Development".Calls
create_time_entrywith today's date, the resolved project ID,7.5hours, and the provided comment.
Result: Confirmation that the entry was created or updated in Beebole.
3. Checking your timesheet
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.
Exposed Tools
list_my_projectsDescription: Returns a list of the user's active projects and tasks.
create_time_entryParameters:
date: Date (formatYYYY-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_entriesParameters:
start_date: Start date (YYYY-MM-DD).end_date: End date (YYYY-MM-DD).
Description: Lists existing time entries for the given period.
Testing
The project uses vitest for unit tests:
npm testTroubleshooting
401 Unauthorized
Ensure your BEEBOLE_API_TOKEN is correct. You can find it in Beebole > Settings > Account.
Project/Task not found
If the assistant cannot find a project, try calling list_my_projects first. Only active projects and tasks are returned by the API.
Connection issues in Claude Desktop
Check the logs in Claude Desktop (often located in
~/Library/Logs/Claude/mcp.logon macOS).Ensure
nodeis in your system PATH and accessible by the Claude app.Make sure you ran
npm run buildto generate thebuild/folder.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Available Tools
4 toolscreate_time_entryA
Create or update a time entry in Beebole. You MUST provide either project_id OR absence_id, but NOT both.
Inputs: date (required), hours (required), comment, task_id, +2 more.
get_time_entriesA
Get time entries for a given period.
Inputs: end_date (required), start_date (required).
list_absence_typesA
List available absence types (Vacation, Sick Leave, etc.).
Inputs: no named parameters.
list_my_projectsA
List active projects and tasks where time can be logged.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored 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.
Maintenance
Related MCP Connectors
timesheet.io MCP server - manage timers, projects, tasks and reports
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that wraps the TimePRO API, enabling AI assistants to automatically create, view, and manage timesheets for authenticated users. It provides tools for searching clients and projects, retrieving configuration defaults, and performing full CRUD operations on timesheet entries.10MIT
- AlicenseBqualityBmaintenanceAn MCP server that provides AI assistants with access to the EARLY time tracking public API, enabling time entry management, activity management, and report generation through natural language.1433 npmMIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI assistants to interact with the Timing application for managing time tracking and tasks, including project and time entry operations.7MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for Timely time tracking API. Connects Claude Code to your Timely account for reading and creating time entries, projects, tasks, and users.9MIT