README.md
Deterministic tools for time, math, counting, randomness, and validation.
basic-mcp
MCP server providing deterministic tools for operations that LLMs commonly struggle with: time, math, counting, randomness, and validation.
Installation
bun install
Usage
With Claude Code
Add to ~/.claude.json:
{
"mcpServers": {
"basic-tools": {
"command": "bun",
"args": ["run", "/path/to/basic-mcp/index.ts"]
}
}
}
Standalone
bun run index.ts
Tools
Time
| Tool | Description |
|---|---|
now |
Get current date/time with timezone support |
date_diff |
Calculate difference between two dates |
date_add |
Add/subtract time from a date |
unix_timestamp |
Convert between Unix timestamps and dates |
Math
| Tool | Description |
|---|---|
calculate |
Evaluate math expressions (supports "15% of 200", sqrt, trig, etc.) |
convert_units |
Convert between units (km to miles, celsius to fahrenheit, etc.) |
statistics |
Calculate mean, median, mode, std dev, min, max, sum |
Strings
| Tool | Description |
|---|---|
count |
Count characters, words, lines, bytes, sentences, paragraphs |
hash |
Generate MD5, SHA1, SHA256, SHA512 hashes |
uuid |
Generate UUID v4 |
base64 |
Encode/decode base64 |
regex_test |
Test strings against regex patterns |
Random
| Tool | Description |
|---|---|
random_int |
Cryptographically secure random integer |
random_float |
Cryptographically secure random float |
random_choice |
Select random item(s) from a list |
shuffle |
Randomly shuffle an array (Fisher-Yates) |
Validation
| Tool | Description |
|---|---|
validate |
Validate email, URL, IPv4, IPv6, UUID, JSON, credit card (Luhn) |
json_parse |
Parse JSON with optional path extraction |
url_parse |
Parse URL into components |
dns_lookup |
DNS lookup (A, AAAA, MX, TXT, NS, CNAME records) |
License
MIT
Tools (20)
nowGet current date/time with timezone supportdate_diffCalculate difference between two datesdate_addAdd/subtract time from a dateunix_timestampConvert between Unix timestamps and datescalculateEvaluate math expressionsconvert_unitsConvert between unitsstatisticsCalculate mean, median, mode, std dev, min, max, sumcountCount characters, words, lines, bytes, sentences, paragraphshashGenerate MD5, SHA1, SHA256, SHA512 hashesuuidGenerate UUID v4base64Encode/decode base64regex_testTest strings against regex patternsrandom_intCryptographically secure random integerrandom_floatCryptographically secure random floatrandom_choiceSelect random item(s) from a listshuffleRandomly shuffle an arrayvalidateValidate email, URL, IPv4, IPv6, UUID, JSON, credit cardjson_parseParse JSON with optional path extractionurl_parseParse URL into componentsdns_lookupDNS lookup for various record typesConfiguration
claude_desktop_config.json
{"mcpServers": {"basic-tools": {"command": "bun", "args": ["run", "/path/to/basic-mcp/index.ts"]}}}Try it
→Calculate the number of days between January 1st, 2024 and today.
→What is 15% of 200 plus the square root of 144?
→Generate a secure UUID and hash the string 'hello world' using SHA256.
→Validate if this string is a properly formatted email address: user@example.com.
→Perform a DNS lookup for the MX records of google.com.