HammerTime MCP server
Commit Nov 13, 2026Generate Discord-compatible timestamps and manage bot settings through an MCP server.
Also known as WentTheFox/HammerTimeBot
- Stars
- 14
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is HammerTime MCP?
HammerTime generates Discord-compatible timestamps and manage bot settings through an MCP server.
Summary generated from the project's README
About HammerTime MCP server
HammerTime provides a specialized interface for generating Discord-compatible timestamps and managing bot settings. It functions as a stateless, streamable HTTP MCP server that allows developers to interact with the same logic used by the HammerTime Discord bot. Users connect via an MCP client by providing a specific URL and an authorization header containing a bearer token created on the HammerTime website.
The server includes tools for various timestamp formats, such as unix, iso, and snowflake, as well as relative time calculations using commands like ago, in, add, and subtract. It also allows for reading and writing account settings. To ensure stability, the service implements rate limits of approximately 60 requests per minute per key. For high-availability environments, it supports running in a cluster with Redis to synchronize rate limiting and request counting across multiple workers.
Written from the project's README. Every use case is checked against a quote from it.
How to install HammerTime MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall HammerTime MCP in Claude Code
$ claude mcp add --transport http hammertime https://api.hammertime.cyou/mcpInstall HammerTime MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hammertime": {
"url": "https://api.hammertime.cyou/mcp"
}
}
}Install HammerTime MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hammertime": {
"type": "http",
"url": "https://api.hammertime.cyou/mcp"
}
}
}Install HammerTime MCP in VS Code CLI
$ code --add-mcp '{"name":"hammertime","type":"http","url":"https://api.hammertime.cyou/mcp"}'Install HammerTime MCP in Codex
$ codex mcp add hammertime --url https://api.hammertime.cyou/mcpInstall HammerTime MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hammertime] url = "https://api.hammertime.cyou/mcp"
Install HammerTime MCP in Gemini CLI
$ gemini mcp add -s user --transport http hammertime https://api.hammertime.cyou/mcpInstall HammerTime MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hammertime": {
"url": "https://api.hammertime.cyou/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablewentthefox/hammertimebot is public and reachablegithub.com/wentthefox/hammertimebot ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/wentthefox/hammertimebot ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubHammerTime API
The public REST API and the MCP server of HammerTime. Every endpoint, and every MCP tool, is the bot command of the same
name, and every input is the command's option with the same name, so POST /at takes year, month, day, hour,
minute, timezone, format and so on, resolved against the saved settings of the account exactly as the bot does it.
The logic is @went.tf/hammertime-core, which the bot uses too.
POST /at, /at12, /iso, /unix, /in, /ago, /add, /subtract, /snowflake |
The commands, scope timestamps:create |
GET/PATCH /settings |
The bot settings of the account, scopes settings:read / settings:write |
GET /me, GET /health |
The key in use, and the service status |
POST /mcp |
The MCP server (Streamable HTTP, stateless), the same API keys |
GET / and GET /generated/api-docs.json |
Swagger UI and the OpenAPI document |
Usage is recorded as the bot's is (same counters, with the source api or mcp) unless the account turned telemetry
off, and the replies carry the run count the way the bot's do.
Keys
Users create them on the HammerTime website (profile page), each acts as one linked Discord account. Send one as
Authorization: Bearer htk_.... The bot has a service key of its own that names the account per request in
X-Discord-User-Id; it is accepted by the REST endpoints for the commands only, not by /mcp.
An MCP client is configured with the URL of /mcp and the header, for example:
{ "mcpServers": { "hammertime": { "type": "http", "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer htk_..." } } } }
The bot as a client
The bot can ask this API to handle its timestamp commands (COMMANDS_API_URL and COMMANDS_API_KEY in the bot's .env, see
.env.example). It sends the options the user gave, as the service key with X-Discord-User-Id, and turns the answer into the
Discord reply. The API has recorded the run by then and the reply carries the note about it, so the bot does not record it a
second time. When the API is down, slow (COMMANDS_API_TIMEOUT_MS), refuses the bot or limits it, the bot handles the
command itself exactly as it did before, including recording the run, so an outage of this service costs nothing but
the logged warning. Input the API rejects is worded by the bot and recorded as it always was.
Rate limits
Each key may make RATE_LIMIT_PER_MINUTE requests (60) on average, with a burst of half of that, across the REST endpoints
and /mcp together. The bot's service key is limited per Discord account it acts for, so one noisy user cannot use up what
the others get. Every response of an authenticated request carries RateLimit-Limit, RateLimit-Remaining and
RateLimit-Reset, and a refused one is a 429 with Retry-After (seconds). /health and the documentation are not limited.
A client address that fails to authenticate AUTH_FAILURES_PER_MINUTE times (20) is turned away with a 429 until it has waited,
before anything is looked up, so a flood of made-up keys does not each cost the Laravel app a lookup. Even a good key from that
address waits, which can catch innocent users behind a shared address, so keep the number generous.
Behind a reverse proxy every client has the proxy's address, so they would all count as one. Set CLIENT_IP_HEADER to a header
the proxy sets to the client's address and overwrites (nginx: proxy_set_header X-Real-IP $remote_addr;), otherwise anyone
could pick the address they are counted under. Nothing runs in the background to clean up after the limits: a bucket is only brought up to date when it is used, and Redis forgets
one by itself when it has filled up again.
Counting in Redis
The server can run as several workers or replicas (see below). Left alone, each counts for itself, so a key can make up to the number of them times
RATE_LIMIT_PER_MINUTE requests, and the same goes for the failed authentications of an address. Set up Redis to count them as one:
either REDIS_URL, or REDIS_HOST with REDIS_PORT, REDIS_USERNAME, REDIS_PASSWORD, REDIS_DB and REDIS_TLS (see
.env.example), and the limits are shared by every worker.
- One Lua script refills the bucket, checks it and spends from it, so two workers can not both take the last token. The keys are
<REDIS_KEY_PREFIX><kind>:<key or address>(hammertime-api:requests:key:42) and expire by themselves. Give the API a database of its own (REDIS_DB), the prefix keeps the keys of the Laravel app, which may share the Redis, safe in any case. - A request never waits for Redis for more than 150 ms. When it does not answer, that request is counted in memory, per worker, as it is without Redis: a limit that is a little looser is better than an API that is down because its rate limiter is. It says so in the log, once a minute at most, and counts in Redis again when Redis is back.
REDIS_TLS=trueis for a Redis on another machine, on this one it is not needed.
Running as a cluster
Several copies of the server can run at once (the former pm2 host ran two workers sharing the port, see pm2.json). A copy
sends ready once it listens and stops on SIGINT by finishing the requests in flight, which is what lets a deploy replace them one
at a time without dropping any (src/graceful-shutdown.ts, the bot has the same one). Nothing a request needs is
kept from the one before. The key cache is per worker, so each of them validates a key against the Laravel app once per
KEY_CACHE_TTL_SECONDS, and the rate limits are per worker too unless Redis is set up.
Where the data lives
Nothing is stored here. The Laravel app (SledgeHammerTime) owns keys, settings and telemetry, and this service talks to its
/internal endpoints with INTERNAL_API_SECRET (see docs/api.md in that repository). Validated keys are remembered for
KEY_CACHE_TTL_SECONDS, so a revoked key keeps working for that long.
Generated parts
src/generated/commands.ts (the request schemas, option types and English texts) is generated from the bot's
src/commands.json and its en-US locale, and docs/openapi/api-docs.json (in the repository root) from the routes.
Both are committed, and the tests fail when they are stale:
pnpm --filter @went.tf/hammertime-api run generate # after changing commands.json or the locale
pnpm --filter @went.tf/hammertime-api run generate -- --commands <path> # from another commands file
pnpm --filter @went.tf/hammertime-api run generate -- --check # write nothing, fail when out of date
pnpm --filter @went.tf/hammertime-api run openapi:sync [-- --check] # after changing routes or their descriptions
Running it
pnpm run build:core && pnpm --filter @went.tf/hammertime-api run build
cp packages/api/.env.example packages/api/.env # fill it in, git ignores it
node packages/api/dist/src/server.js # reads packages/api/.env by itself
In production it runs from the container image on the cluster, deployed with the rest of the app by the Deploy workflow (see the
root README). Deploy the Laravel app first, since this service calls its internal endpoints. The former pm2 host ran it as
HammerTimeBot:Api in pm2.json, listening on 127.0.0.1:3010 only behind nginx (nginx/api.hammertime.cyou.conf), when
packages/api/.env existed, see deploy.conf.
Tests
pnpm run test:packages from the root (core and API). They run the app in-process against an in-memory backend, the MCP
tests use the real MCP SDK client.
Listing in the MCP Registry
server.json is what the MCP Registry lists: the endpoint of the MCP server and
that it wants the API key as a bearer token. The registry only keeps metadata, so there is no package to publish.
The name is io.github.WentTheFox/hammertime. The workflow in .github/workflows/publish-mcp.yml authenticates with the
OIDC token of GitHub Actions, which proves that the repository belongs to that owner, so no secret is stored anywhere.
To publish a version:
- Raise
versionin bothpackages/api/package.jsonandpackages/api/server.json. A test fails when they differ. - Merge it, then tag it:
git tag mcp-v0.2.0 && git push origin mcp-v0.2.0.
The workflow tests the packages, checks that the tag matches server.json, validates it with mcp-publisher validate and publishes.
A version can be published once. To try the file without publishing, run mcp-publisher validate in packages/api.
HammerTime MCP questions
How do I add HammerTime MCP to Claude Code?
Run claude mcp add --transport http hammertime https://api.hammertime.cyou/mcp in your terminal. Add --scope user to make it available in every project.
How do I add HammerTime MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I authenticate with the HammerTime MCP server?
You can authenticate by creating keys on the HammerTime website and sending one as a Bearer token in the Authorization header.
Are there rate limits on the API?
Yes, each key is limited to an average of 60 requests per minute, with a burst capacity of 30 requests.