timetta-mcp
The timetta-mcp server acts as a universal read-write MCP gateway to the Timetta time-tracking platform's OData API, enabling you to explore, query, create, update, and delete records via clients like Claude Desktop or Gemini CLI.
Available tools:
list_entities()— Discover all queryable OData entity sets (e.g.,TimeEntries,Users,Projects)get_entity_schema(entity)— Inspect field names, data types, and navigation properties for a specific entity before queryingquery_odata(entity, ...)— Query any entity with full OData semantics:Filter records (
filter), select specific fields (select), expand related entities (expand), sort (orderby), and paginate (topdefault 50 / max 200,skip)
create_entity(entity, data)— Create new records via HTTP POSTupdate_entity(entity, id, data)— Partially update existing records via HTTP PATCHdelete_entity(entity, id)— Delete records by ID via HTTP DELETE
Notes:
Write operations (create/update/delete) depend on the permissions of the token used; a read-only token restricts the server accordingly
Supports both static API token and OAuth (email/password) authentication
Base URL, auth URL, and credential storage path are all configurable
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., "@timetta-mcp query time entries for last week"
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.
timetta-mcp
MCP server exposing the Timetta main OData API to MCP clients (Claude Desktop, Claude Code, Codex, Gemini CLI, etc.) as a universal read-write gateway.
Tools
Generic CRUD
list_entities()— list queryable OData entities.get_entity_schema(entity)— fields, types and navigation properties of an entity. Call this first to learn real field names.query_odata(entity, filter?, select?, expand?, orderby?, top?, skip?)— query an entity using OData semantics (without the leading$).topdefaults to 50, capped at 200.create_entity(entity, data)— create a record (POST).datais a JSON object of field -> value.update_entity(entity, id, data)— update a record by id (PATCH).dataholds only the fields to change.delete_entity(entity, id)— delete a record by id (DELETE).
Composite (reference-data resolved)
create_issue(title, description?, type_hint?, project_id?, priority_code?, project_task_id?, project_task_hint?, parent_id?, assignee_id?)— create a Timetta issue in one call. Resolves issue type, priority, and project task from reference catalogs internally.link_issues(source_id, destination_id, link_type_name?)— link two issues, resolving the link type by name.attach_file(issue_key_or_id, file_path, filename?)— attach a local file to an issue, resolving it by key or numeric id.change_issue_status(issue_key, status_code)— change the status of an issue. Resolves the status code against the DirectoryEntries catalog.
Related MCP server: getdot-database-skills
Configuration
Variable | Required | Default | Notes |
| one of the two | — | Static Token API value (Bearer), TTL 1 year. Takes priority when set. |
| for OAuth |
| Public OAuth client id used by |
| no |
| OAuth auth server. |
| no | platform default | Where OAuth tokens are stored. Default: |
| no |
| OData base URL. |
| no | — | Default project for |
| no | — | Default priority code for |
| no | — | Default assignee for |
| no | — | Default project task for |
The server can create, update and delete records. Effective permissions are governed entirely by the token — use a read-only Timetta token if write access is not needed.
Authentication
The server picks credentials in this order: TIMETTA_API_TOKEN env var →
credentials file written by timetta-mcp login → otherwise an error asking you
to log in.
Run a one-time login and choose a method (like the Timetta VS Code extension):
timetta-mcp loginToken API (recommended; works with SSO accounts). Paste a long-lived token generated in Timetta settings (TTL ~1 year). It is saved to
TIMETTA_CREDENTIALS_PATHand sent as a Bearer token. No refresh needed.Email + password (OAuth password grant). Exchanges your Timetta email/password for tokens via
grant_type=password(clientexternal) and saves the refresh token. The password is never stored — only the resulting tokens. The server refreshes the access token automatically; re-runtimetta-mcp loginif the refresh token expires (Timetta refresh tokens last roughly 15 days of inactivity).
These are the only two methods Timetta documents for integrations; it offers no
self-service OAuth client registration or browser authorization_code flow.
For CI / automation you can skip login entirely and set TIMETTA_API_TOKEN —
it always takes priority.
Tip: run
timetta-mcpfrom this checkout withuv run timetta-mcp …(oruvx --no-cache --from . timetta-mcp …). Plainuvx --from <path>caches the built environment and may run stale code after you edit the source.
Run
Locally from a checkout:
uvx --from . timetta-mcpFrom the repository:
uvx --from git+https://github.com/sh1rokovs/timetta-mcp timetta-mcpClaude Desktop config
{
"mcpServers": {
"timetta": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sh1rokovs/timetta-mcp", "timetta-mcp"],
"env": { "TIMETTA_API_TOKEN": "YOUR_TOKEN" }
}
}
}Claude Code
CLI command (installs the server straight from GitHub via uvx):
claude mcp add timetta \
--env TIMETTA_API_TOKEN=YOUR_TOKEN \
-- uvx --from git+https://github.com/sh1rokovs/timetta-mcp timetta-mcpScope is selected with -s: local (default, this project only), user
(all projects), or project (writes a committed .mcp.json). To share the
server with everyone who clones the repo, add a .mcp.json at the project root:
{
"mcpServers": {
"timetta": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sh1rokovs/timetta-mcp", "timetta-mcp"],
"env": { "TIMETTA_API_TOKEN": "${TIMETTA_API_TOKEN}" }
}
}
}${TIMETTA_API_TOKEN} is read from the environment, so the token never lands
in the repo. Verify with claude mcp list / claude mcp get timetta.
Codex CLI
Add the server to ~/.codex/config.toml:
[mcp_servers.timetta]
command = "uvx"
args = ["--from", "git+https://github.com/sh1rokovs/timetta-mcp", "timetta-mcp"]
env = { TIMETTA_API_TOKEN = "YOUR_TOKEN" }Or via the CLI:
codex mcp add timetta \
--env TIMETTA_API_TOKEN=YOUR_TOKEN \
-- uvx --from git+https://github.com/sh1rokovs/timetta-mcp timetta-mcpGemini CLI
Add the server to ~/.gemini/settings.json (user scope) or
.gemini/settings.json in the project root (committed, shared scope):
{
"mcpServers": {
"timetta": {
"command": "uvx",
"args": ["--from", "git+https://github.com/sh1rokovs/timetta-mcp", "timetta-mcp"],
"env": { "TIMETTA_API_TOKEN": "$TIMETTA_API_TOKEN" }
}
}
}List configured servers with /mcp inside the Gemini CLI.
Development
uv sync
uv run pytestExample
get_entity_schema("TimeEntries")
query_odata("TimeEntries", filter="Date ge 2024-01-01 and Date le 2024-01-31",
expand="Project,User", select="Date,Hours,Comment")Available Tools
3 toolsget_entity_schemaA
Get fields, types and navigation properties for one Timetta entity (e.g. 'Users', 'TimeEntries'). Call this before query_odata to learn real field names.
Inputs: entity (required). Returns: result
list_entitiesA
List the queryable Timetta OData entities (EntitySet names).
Inputs: no named parameters. Returns: result
query_odataA
Query a Timetta OData entity.
Args use OData semantics ($filter, $select, $expand, $orderby, $top, $skip) without the leading '$'. Example: entity='TimeEntries', filter='Date ge 2024-01-01', expand='Project,User', select='Date,Hours'. top defaults to 50 and is capped at 200; use skip to paginate. Returns a JSON array of rows, or 'Error: ...' on failure.
Inputs: entity (required), filter, select, expand, +3 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: listing entities, retrieving schema for a specific entity, and querying data. No overlap or ambiguity.
All tools follow a consistent verb_noun pattern in snake_case: get_entity_schema, list_entities, query_odata. The pattern is uniform and predictable.
Three tools is minimal but fits the focused scope of exploring and querying Timetta OData. It is not overly sparse for a read-only adapter; could potentially include more but earns its place.
The tool set covers the essential read operations: listing available entities, understanding their schema, and querying with rich OData semantics. For a read-only interface, there are no obvious gaps; write operations are likely out of scope.
Maintenance
Related MCP Connectors
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MCP server for searching Airweave collections with natural language queries.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP Server that enables natural language interaction with the Open Policy Agent REST API, allowing users to manage policies, decisions, and data through conversational interfaces.1-
- AlicenseNot gradedqualityDmaintenanceMCP server providing a single query tool to execute SQL against GetDot Database, enabling schema discovery, data loading, and querying via natural language.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server for OData v4 endpoints, especially Microsoft Dataverse/Dynamics 365, enabling authentication, schema discovery, querying, CRUD, and more via natural language.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for natural language queries against CDS db-layer entities; automatically discovers schema, generates SQL JOINs, and returns rows.86 npmMIT