A Model Context Protocol (MCP) server for interacting with the Noko time tracking API.
This MCP server allows Claude and other AI assistants to:
- List time entries with filtering options
- Create new time entries
- List projects
- List users
# Clone the repository
git clone https://github.com/yourusername/mcp-nokotime.git
cd mcp-nokotime
# Install dependencies
npm install
# Build the project
npm run build
You can obtain your Noko API token from your Noko account settings.
An .env
file will be used when running the server directly via npm start
or during development. Please put your API token in the .env file.
NOKO_API_TOKEN=your_noko_api_token
To use this MCP server with Claude Desktop, add the following configuration to your claude_desktop_config.json
(located at ~/Library/Application Support/Claude/claude_desktop_config.json
on macOS or %APPDATA%\Claude\claude_desktop_config.json
on Windows):
{
"mcpServers": {
"noko": {
"command": "node",
"args": [
"/path/to/mcp-nokotime"
],
"env": {
"NOKO_API_TOKEN": "your_noko_api_token"
}
}
}
}
Note about environment variables: While the project uses a .env
file for direct server execution, Claude Desktop requires the environment variables to be specified in the claude_desktop_config.json
file as shown above. The .env
file is not automatically read when Claude Desktop launches the server.
Make sure to:
- Replace
/path/to/mcp-nokotime
with the actual path where you cloned the repository - Replace
your_noko_api_token
with your actual Noko API token from your Noko account settings (same token as in your.env
file) - Ensure you have Node.js installed on your system (verify by running
node --version
in your terminal) - Restart Claude Desktop after making these changes
The server includes built-in safety features like requiring confirmation for destructive operations (edit/delete), so you don't need to worry about accidental modifications to your time entries.
npm start
npm run dev
The server provides the following tools to AI assistants:
-
noko_list_entries
- List time entries with optional filters and pagination- Optional parameters:
user_ids
- Comma-separated list of user IDs to filter by (e.g., '1,2,3')project_ids
- Comma-separated list of project IDs to filter by (e.g., '4,5,6')description
- Filter entries containing this text in their descriptiontag_ids
- Comma-separated list of tag IDs to filter by (e.g., '7,8,9')tag_filter_type
- How to filter by tags: 'and' (default) or 'combination of'invoice_ids
- Comma-separated list of invoice IDs to filter byimport_ids
- Comma-separated list of import IDs to filter byfrom
- Only include entries from or after this date (YYYY-MM-DD)to
- Only include entries on or before this date (YYYY-MM-DD)invoiced
- Filter by invoice status: true for invoiced entries, false for uninvoiced entriesinvoiced_at_from
/invoiced_at_to
- Filter by invoice date range (YYYY-MM-DD)updated_from
/updated_to
- Filter by update timestamp range (YYYY-MM-DDTHH:MM:SSZ)billable
- Filter by billable status: true for billable entries, false for unbillable entriesapproved_at_from
/approved_at_to
- Filter by approval date range (YYYY-MM-DD)approved_by_ids
- Comma-separated list of user IDs who approved entriesper_page
- Number of results per page (1-1000, default: 30)page
- Page number (starts at 1)
- Returns:
- Array of entry objects when no pagination is needed
- Object with
data
(array of entries) andpagination
properties when pagination is present - Pagination includes links to
first
,last
,next
, andprev
pages when available
- Optional parameters:
-
noko_create_entry
- Create a new time entry- Required parameters:
date
,minutes
,description
- Optional parameters:
project_id
,user_id
,billable
,tags
,invoice_id
- Required parameters:
-
noko_edit_entry
- Edit an existing time entry- Required parameters:
id
- ID of the entry to editconfirm
- Must be set to true to confirm the edit operation
- Optional parameters:
date
- Date of the entry in YYYY-MM-DD formatminutes
- Duration of the entry in minutesdescription
- Description of the work performedproject_id
- ID of the project this entry belongs touser_id
- ID of the user this entry belongs tobillable
- Whether this entry is billabletags
- Array of tags to associate with this entryinvoice_id
- ID of an invoice to associate with this entry
- Required parameters:
-
noko_delete_entry
- Delete a time entry permanently- Required parameters:
id
- ID of the entry to deleteconfirm
- Must be set to true to confirm the delete operation
- Note: Entries cannot be deleted if they have been invoiced, are associated with an archived project, or are approved and locked
- Required parameters:
-
noko_list_projects
- List all available projects with optional filtering and pagination- Optional parameters:
name
- Filter projects by name (partial matching)project_group_ids
- Comma-separated list of project group IDs to filter by (e.g., '1,2,3')billing_increment
- Filter by billing increment in minutes: "1", "5", "6", "10", "15", "20", "30", "60" (default: "15")enabled
- Filter by project status: true for enabled projects, false for archived projectsbillable
- Filter by billing status: true for billable projects, false for unbillable projectsper_page
- Number of results per page (1-1000, default: 30)page
- Page number (starts at 1)
- Returns:
- Array of project objects when no pagination is needed
- Object with
data
(array of projects) andpagination
properties when pagination is present - Pagination includes links to
first
,last
,next
, andprev
pages when available
- Optional parameters:
-
noko_list_users
- List all users with optional filtering and pagination- Optional parameters:
name
- Filter users by name (partial matching)email
- Filter users by email (partial matching)state
- Filter by account state: "disabled", "pending", "active", "suspended", or "all" (default: all)role
- Filter by role: "supervisor", "leader", "coworker", or "contractor"per_page
- Number of results per page (1-1000, default: 30)page
- Page number (starts at 1)
- Returns:
- Array of user objects when no pagination is needed
- Object with
data
(array of users) andpagination
properties when pagination is present - Pagination includes links to
first
,last
,next
, andprev
pages when available
- Optional parameters:
Tools that perform destructive operations (like noko_edit_entry
and noko_delete_entry
) include a required confirm
parameter which must be explicitly set to true
before the operation will proceed.
When using an AI assistant like Claude with these tools:
- When you request a destructive action, the assistant will recognize that confirmation is required
- The assistant will ask you to confirm before proceeding with the operation
- Only after receiving your confirmation will the assistant set
confirm: true
and execute the operation
This provides an additional safety layer to prevent accidental modifications or deletions of your time entries.
Example interaction:
User: Delete time entry 12345
Assistant: I can help you delete entry #12345. This action is permanent and cannot be undone. Would you like to proceed?
User: Yes, please delete it
Assistant: [Executes deletion with confirm=true] Entry #12345 has been successfully deleted.
MIT