Use with AI
The timepicker-ui-mcp server gives your AI assistant the library's options, events, themes and CSS classes, read from the source, so it does not have to guess them.
Install
#The server runs on your machine through npx. It needs Node 20 or newer and no API key. It works with MCP clients on the 2025 protocol and on the 2026-07-28 revision. Its releases are listed in the MCP server changelog.
claude mcp add timepicker-ui -- npx -y timepicker-ui-mcp
By default, only you can use the server, and only in this project. Add -s user after add to use it in every project, or -s project to save it in .mcp.json and share it with your team.
On native Windows, wrap npx in cmd /c:
claude mcp add timepicker-ui -- cmd /c npx -y timepicker-ui-mcp
What it can do
#The server has 17 tools. The assistant chooses which ones to call from your request.
| Tool | Group | What it does |
|---|---|---|
search_reference | Look up | Keyword search across options (nested fields included), events, CSS variables, CSS classes, methods, themes and troubleshooting entries, for when the exact name is not known. |
list_themes | Look up | Built-in themes and their CSS import paths. |
list_modes | Look up | UI modes (clock, wheel, compact-wheel) and the plugin each one needs. |
list_plugins | Look up | Optional plugins (range, timezone, wheel) with their import paths. |
list_events | Look up | Events with their payload fields. Pass includeInternal or includeDeprecated to also get internal or deprecated events. |
list_api | Look up | Instance and static methods, plus what getValue() returns and setValue() accepts. Deprecated methods are flagged. |
list_css_classes | Look up | The tp-ui- class names and state modifiers, each with an example selector. |
list_css_variables | Look up | The --tp- variables with their group and default value. group narrows the list. Variables that no rule reads are left out unless includeUnread is set. |
get_options | Look up | Options with type, default and description. Pass group to get one group. Deprecated options appear only with includeDeprecated. |
explain_option | Look up | Full detail for one option, by group and name. A dotted name such as disabledTime.ranges reaches nested fields. |
get_theme | Look up | The --tp- variables a built-in theme sets, with their values. |
framework_recipe | Generate | Setup code and server rendering notes for vanilla JS, React, Next.js, Vue, Angular or Svelte, plus the react-wrapper recipe for timepicker-ui-react. |
generate_snippet | Generate | Vanilla JS or React setup code, with the CSS imports and plugin registration. Also covers the seconds field and clockType: 'auto'. |
generate_custom_theme | Generate | Writes a .tp-ui-wrapper.<name> block for a class you pass in ui.cssClass, from your --tp- overrides or as a scaffold to edit. |
migration_guide | Generate | The v3 to v4 option mapping, the changes from 4.3 to 4.4 and from 4.4 to 4.5, and the draft 4.5 to 5.0 path with its renamed and removed tables. |
validate_time | Check | Checks HH:MM, HH:MM:SS, h:MM AM/PM or h:MM:SS AM/PM against a 12h or 24h clock. |
validate_disabled_time | Check | Checks a clock.disabledTime config: the hour, minute and second lists and the range strings. |
It also has four resources, which some clients let you attach to a chat as context: timepicker-ui://reference (a summary of the options), timepicker-ui://css-variables (every --tp- variable with its group, its default and whether any rule reads it), timepicker-ui://custom-theme-guide (a custom theme built on ui.cssClass) and timepicker-ui://troubleshooting (the same entries as the troubleshooting page).
Four prompts start a task and tell the assistant which tools to use: integrate takes a framework, build-custom-theme a description of the look you want, and migrate-v3-to-v4 your v3 code. prepare-for-v5 takes your 4.x code and replaces deprecated API with the names 5.0 keeps.
Example prompts
#Ask in your own words. Each prompt below matches one or two tools:
- "Add a 24-hour timepicker with the dark theme to my Next.js page." Tools:
framework_recipe,generate_snippet. - "Make a custom theme with #0f62fe as the primary color." Tool:
generate_custom_theme. - "Migrate this v3 timepicker config to v4." Tool:
migration_guide. - "Is this
disabledTimeconfig valid?" Tool:validate_disabled_time. - "Which option blocks the lunch break?" Tool:
search_reference.
Troubleshooting
#The server does not start
Check that node --version prints 20 or newer. Then start the server in a terminal, where you can see its error:
npx -y timepicker-ui-mcp
If it starts, it prints timepicker-ui MCP server running on stdio and waits for a client. Stop it with Ctrl+C.
The tools do not show up
Quit the client completely and open it again. If the tools are still missing, connect to the server with the MCP Inspector. It lists the tools, resources and prompts the server offers, and you can call each tool from there:
npx @modelcontextprotocol/inspector npx -y timepicker-ui-mcp
The assistant does not use the tools
The assistant decides when to call a tool, and it can still answer from memory. Name the server in your prompt, for example "use the timepicker-ui MCP server".
llms.txt
#The site also publishes /llms.txt, a plain-text index of these docs for AI tools: a short summary of the library and a link to each page in the navigation. Give its URL to an assistant that cannot connect to an MCP server.