Skip to main content
Glama
mcp-utility-server

mcp-utility-server

MCP Utility Server

A production-grade Model Context Protocol server with 10 utility tools for daily operations. Built with FastMCP, stdlib-first, fully tested (TDD).

Why this server: it demonstrates real MCP engineering — not a hello-world. It includes:

  • Retry/backoff with jitter on all external HTTP calls (429/5xx handling)

  • State persistence for page monitoring (SHA-256 diff tracking)

  • Observability — per-tool retry counters exposed as an MCP tool

  • Sandboxing for file operations (optional FILE_SANDBOX)

  • Deterministic outputs (word-of-day selection is hash-based, same all day)

  • ~30 pytest tests with mocked network (no external deps in CI)

Tools

Tool

Description

file_convert

Convert MD/HTML/CSV/JSON/Text formats (stdlib-only)

page_monitor

Poll a URL, SHA-256 diff, optional Telegram notify on change

telegram_poll

Send Telegram polls (2-10 options)

trade_signal

Binance OHLCV → RSI(14) + SMA20/SMA50 cross → BUY/SELL/HOLD

backtest_report

Parse Freqtrade backtest JSON → markdown digest

word_of_day

German word (A1/A2) with translations, IPA, examples — deterministic per date

soc_lang_card

Daily language card: German word + SOC term (EN/DE/RU)

weather_alert

Open-Meteo threshold alerts (wind/rain) for configured cities

antimatter_scan

Scan trading logs for trades/errors/signals + resonance score

mcp_stats

Retry/backoff observability snapshot

Related MCP server: agent-utils-mcp

Quick start

# Install
uv sync

# Run (stdio transport — default for MCP clients)
uv run server.py

# Run (SSE transport — for remote clients)
uv run server.py --transport sse

# Test
uv run pytest

Configuration (env vars)

Env

Default

Purpose

TELEGRAM_BOT_TOKEN

—

Required for telegram_poll / page_monitor notify

TELEGRAM_CHAT_ID

—

Default chat for Telegram tools

FILE_SANDBOX

unset (allow-all)

Restrict file_convert to a directory. Set on production!

STATE_DIR

~/.mcp-utility/state

Page-monitor state location

HTTP_MAX_RETRIES

2

Max retries on 429/5xx (1 initial + N retries)

HTTP_RETRY_DELAY

1.0

Base backoff seconds (exponential, ±20% jitter)

MCP_STATS_PATH

/tmp/mcp_utility_stats.json

Retry stats persistence

MCP_LOG

INFO

Logging level

MCP_TRANSPORT

stdio

stdio or sse

Example: Claude Desktop

{
  "mcpServers": {
    "mcp-utility": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-utility-server", "server.py"]
    }
  }
}

Example: trade signal

echo '{"symbol":"BTCUSDT","interval":"1d"}' | uv run server.py
# → {"status":"ok","symbol":"BTCUSDT","rsi":42.3,"ma_fast":42100.0,
#    "ma_slow":41800.5,"signal":"BUY","reasons":["MA20 > MA50"],...}

Security notes

  • file_convert accepts any path when FILE_SANDBOX is unset — always set it in production

  • Telegram token is read from env only, never logged

  • antimatter_scan("docker:...") executes docker logs — requires docker socket access

License

MIT

Available Tools

10 tools
antimatter_scanA

Scan Freqtrade logs for trades / errors / signals.

logs_path: file path (e.g. /tmp/freqtrade.log) OR "docker:container_name" Returns dict: {status, source, lines_scanned, trades_count, buy_count, sell_count, errors_count, signals_count, recent_errors, recent_signals, score, error?}

Inputs: logs_path (required), max_errors. Returns: result

backtest_reportA

Parse Freqtrade backtest-result JSON → markdown digest.

Returns dict: {status, strategy, timeframe, trades_total, profit_pct, winrate_pct, avg_profit_pct, top_trades_md, hourly_md, error?}

Inputs: file_path (required), top_n. Returns: result

file_convertA

Convert between MD/HTML/CSV/JSON/Text formats.

Supported: md -> html | txt | json html-> md csv -> json | md_table json-> csv | md_table | pretty txt -> md

Returns dict: {status, output_path, output_format, preview, error?}

Inputs: fmt (required), path (required). Returns: result

mcp_statsA

observability — Snapshot of in-memory retry counter per tool.

Returns dict: {status, stats:{tool: {retries, events, last_status, last_error, last_at}}, total_retries, total_events, stats_path, snapshot_at} Same data is also persisted to the stats JSON file for cross-process visibility.

Inputs: no named parameters. Returns: result

page_monitorA

Check URL for changes; persist hash; notify Telegram on change.

State stored in ~/.hermes/monitors/<sha256(url)[:16]>.json. Returns dict: {status, url, hash, is_first_check, changed, diff_summary, sent_to_telegram, error?}

Inputs: url (required), chat_id, selector. Returns: result

soc_lang_cardA

Daily language card: German word (A1/A2) + SOC term (EN/DE/RU).

level: A1 | A2 focus: optional context filter: 'SOC Fundamentals' | 'Detect' | 'Triage' | 'Correlate' | 'Respond' | 'Visualize' | 'Notify' | 'Interview' Selection is deterministic (hash of date) — same card all day. Returns dict: {status, selected_for_date, german_word, soc_term, fetched_at}

Inputs: focus, level. Returns: result

telegram_pollC

Send a Telegram Poll to configured/default chat.

Returns dict: {status, message_id, poll_id, chat_id, question, error?}

Inputs: options (required), question (required), chat_id, is_anonymous. Returns: result

trade_signalA

Binance OHLCV → RSI(14) + SMA20/SMA50 cross → BUY/SELL/HOLD.

symbol examples: BTCUSDT, ETHUSDT, SOLUSDT interval: 1h | 4h | 1d | 1w Returns dict: {status, symbol, interval, price, rsi, ma_fast, ma_slow, ma_signal, signal, error?}

Inputs: symbol, interval. Returns: result

weather_alertA

Check weather for cities; return alerts when thresholds exceeded.

Default cities: Sumy, Lviv, Budapest, Vienna. Open-Meteo (no API key required). Returns dict: {status, cities_checked, alerts:[{city,condition,value,threshold,severity}], errors}

Inputs: cities, rain_threshold_mmh, wind_threshold_kmh, temp_change_threshold. Returns: result

word_of_dayA

German word of the day with translations + IPA + examples.

level: A1 | A2 Selection is deterministic (hash of date+level) — same word all day. Returns dict: {status, word, level, pos, translations, examples, pronunciation_url, fetched_at}

Inputs: level. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 10 tools

    Disambiguation4/5

    Most tools target clearly distinct functions such as file conversion, Telegram polls, trading signals, weather alerts, and log scanning. The main ambiguity is between word_of_day and soc_lang_card, since both serve daily German A1/A2 content and soc_lang_card largely supersedes word_of_day.

    Naming Consistency3/5

    All names use lowercase snake_case, but the pattern is inconsistent: some are noun_action (file_convert, page_monitor), while others are noun_noun or phrase-like (mcp_stats, soc_lang_card, word_of_day). The names are readable but not highly predictable.

    Tool Count4/5

    Ten tools is a reasonable count for a general utility server and none are clearly redundant. However, the server has no unified scope—monitoring, trading, language learning, weather, and observability are all mixed together—so the count fits numerically but the scope is broad.

    Completeness3/5

    Individual utilities are mostly self-contained, but there are notable gaps: page_monitor lacks monitor management, weather_alert has no city configuration, and the trading/log tools are one-shot analyzers without related operations. Because the server's domain is generic 'utilities,' completeness is hard to establish.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive collection of 103 tools providing capabilities for text processing, data analysis, web development, and business management in a single server. It is designed for rapid deployment to Vercel and integrates seamlessly with MCP clients like Claude and Cursor to automate diverse workflows.
      -
    • F
      license
      A
      quality
      C
      maintenance
      Swiss-army-knife utility MCP server for AI agents. 18 tools for JSON validation/formatting, base64 encode/decode, hash generation, UUID generation, URL parsing, regex testing, markdown↔HTML conversion, text stats, slug generation, datetime conversion, cron parsing, text diffing, CSV↔JSON conversion, and JWT decoding. Zero API Key required
      18
      5
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 24 deterministic developer utilities as MCP tools — encoders and hashers, UUID/ULID and timestamp helpers, color, CSS, cron and permission converters, JSON/YAML/XML/SQL/TypeScript transformers, and a web page-to-markdown fetcher. Runs locally over stdio so agents get byte-exact results instead of approximating computations, with only the markdown fetcher making network requests.
      MIT