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