A collection of production-ready Model Context Protocol (MCP) servers written in TypeScript to extend AI coding assistants with reproducible tooling. Every server communicates over stdio and can be registered with any MCP-compliant client (Claude Desktop, CLI agents, IDE integrations) to add focused capabilities without leaking sensitive workspace data.

• Overview
• Prerequisites
• Quick Start
• Integration With MCP Clients
• Server Reference
  • archive-mcp - Archive Utilities
  • browser-mcp - Headless Browser Automation
  • curl - HTTP Request Workbench
  • dice-roll - Gaming Dice Simulator
  • easy-view - Read-Only Workspace Explorer
  • file-download - Persistent Download Sink
  • ffmpeg-mcp - Media Processing Toolkit
  • html-mcp - HTML Parsing Toolkit
  • imagemagick-mcp - Image Processing Toolkit
  • json-mcp - Structured Data Toolkit
  • markdown-mcp - Markdown Utilities
  • osrs-lookup - Old School RuneScape Lookup
  • time - Time Zone Utilities
  • yt-dlp-mcp - Media Download Suite
• Development Workflow
• Troubleshooting
• License

• Each server is self-contained (its own package.json, src, and compiled dist output) so you can build, deploy, or version them independently.
• Tooling covers HTTP inspection, browser automation, archive management, FFmpeg-powered media editing, ImageMagick-powered image processing, large-scale media downloading via yt-dlp, dice rolling, read-only codebase exploration, controlled file download management, structured data conversions (JSON/YAML/XML), Markdown analysis, Old School RuneScape data lookups, and timezone utilities.
• All servers log operational details to stderr to keep stdout clean for MCP responses.
• Distributed under the MIT license for unrestricted commercial and personal use.

• Node.js 18 LTS or newer (ships with npm 9+). Earlier runtimes may lack modern ECMAScript APIs used by @modelcontextprotocol/sdk.
• npm (installed with Node) or another Node package manager if you prefer (pnpm, yarn). Commands below use npm.
• The curl command-line client accessible in your PATH for the HTTP workbench. Most macOS and Linux distributions include it; on Windows install curl or enable it via Windows features.
• A terminal that supports the scripts you invoke. On Windows, the provided npm run clean uses Unix rm -rf; either run it from Git Bash/WSL or replace with Remove-Item -Recurse -Force dist.
• An MCP-compatible client (for example, Claude Desktop >= v1.5, an IDE with MCP support, or a custom automation harness).

1. Clone or open the repository.

   git clone https://github.com/Ddemon26/custom-mcp-servers.git
   cd custom-mcp-servers

2. Install dependencies. Run npm install inside each server the first time you clone the repo and whenever that server’s package.json changes.

3. Build the TypeScript output. From the server directory, run npm run build before you register it with an MCP client; this generates the dist/server.js entry point.

4. Run a server locally (manual verification).

   npm run start

   The process binds stdio and will wait for requests from an MCP client. Stop with Ctrl+C after confirming the build.

5. (Optional) Use live reload while iterating.

   npm run dev

   ts-node starts the server directly from src/server.ts, recompiling on each launch. Ideal for debugging before producing a release build.

All servers speak MCP over stdio. You typically register them in your client's configuration so it spawns the process and proxies requests/responses automatically.

1. Build the server (npm run build) you want to expose.

2. Add an entry to your MCP client configuration. Below is a Claude Desktop example for Windows; adapt the paths for macOS (~/Library/Application Support/Claude/claude_desktop_config.json) or Linux (~/.config/Claude/claude_desktop_config.json).

   {
     "mcpServers": {
       "archive-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/archive-mcp/src/server.js"]
       },
       "browser-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/browser-mcp/src/server.js"]
       },
       "curl": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/curl/src/server.js"]
       },
       "dice-roll": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/dice-roll/src/server.js"]
       },
       "easy-view": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/easy-view/src/server.js"]
       },
       "file-download": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/file-download/src/server.js"]
       },
       "ffmpeg-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/ffmpeg-mcp/src/server.js"]
       },
       "yt-dlp-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/yt-dlp-mcp/src/server.js"]
       },
       "html-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/html-mcp/src/server.js"]
       },
       "imagemagick-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/imagemagick-mcp/src/server.js"]
       },
       "json-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/json-mcp/src/server.js"]
       },
       "markdown-mcp": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/markdown-mcp/src/server.js"]
       },
       "osrs-lookup": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/osrs-lookup/src/server.js"]
       },
       "time": {
         "command": "node",
         "args": ["/your/path/to/custom-mcp-servers/time/src/server.js"]
       }
     }
   }

   • Use forward slashes in JSON to avoid escaping backslashes.
   • Ensure the working directory matches the project root so relative paths (for example, the easy-view index) resolve correctly.

3. Restart the client so it reloads the MCP configuration.

4. Invoke tools by name inside your client (navigate, create_zip, convert_video, download_video, parse_html, resize_image, curl_execute, roll_d100, scan_directory, save_text_file, format_json, markdown_to_html, get_current_time, etc.). The server responses appear in the assistant panel.

• Path: archive-mcp/
• Purpose: Create and extract ZIP/TAR/TAR.GZ archives plus gzip individual files.
• Key behaviours:
  • Ensures destination folders exist before writing archives or compressed files.
  • Accepts JSON-encoded path arrays for multi-source operations so assistants can build inputs dynamically.
  • Supports stripComponents for tar-based extraction to drop leading directory levels.

Usage tips

• Provide absolute paths when possible; relative inputs resolve from the server’s working directory.
• Encode sources as JSON.stringify([...]) before passing to keep argument schemas simple.
• Extraction overwrites existing files—target empty temp directories when unsure.

• Path: browser-mcp/
• Purpose: Drive a headless Chromium instance for navigation, scraping, and capture tasks.
• Key behaviours:
  • Reuses a single Puppeteer browser/page between calls for performance; call close_browser to reset.
  • Launches with --no-sandbox flags for compatibility with CI and container environments.
  • Returns screenshots as base64 when no path is supplied, avoiding filesystem writes by default.

Usage tips

• Call navigate before other actions to guarantee the page exists.
• Pass JSON strings (e.g., JSON.stringify({ "#email": "user@example.com" })) for fields, selectors, and cookies.
• Use wait_for_selector between navigation and extraction to ensure dynamic content is present.

• Path: curl/
• Purpose: Issue HTTP requests with the system curl binary, capture responses once, and explore them without spending additional model tokens.
• Key behaviours:
  • Stores up to 50 responses in memory with metadata (status, headers, body preview). Oldest entries are pruned automatically.
  • Errors returned by curl (certificate errors, timeouts, DNS failures) are captured as synthetic responses so you can review failure details.
  • Adds -s -i flags to minimise progress output and include response headers automatically.
  • Supports request bodies (-d) for POST/PUT/PATCH with shell-safe quoting.

Usage tips

• curl_list shows truncated IDs (first 8 characters); pass the full UUID to curl_show or curl_clear.
• Set body_lines: 0 when calling curl_show to stream the whole payload if you are comfortable with the token cost.
• Provide headers as a JSON object (for example, { "Authorization": "Bearer <token>" }).
• If you see curl command errors, verify the executable is in your PATH or supply absolute URLs.

• Path: dice-roll/
• Purpose: Provide predictable, validated dice rolls for tabletop or gaming scenarios.
• Key behaviours:
  • Validates side counts (2-1000) and roll counts (1-20) to stop runaway requests.
  • Uses Node's Math.random, which is fine for casual use but not cryptographically secure.
  • Formats output with total, individual rolls, and percentile support (00-99 by rolling two d10s).

Usage tips

• Arguments are parsed as strings to match typical MCP payloads; whitespace is trimmed automatically.
• The server logs rolls to stderr (useful when debugging or auditing results).
• Because randomness uses Math.random, do not rely on it for security-critical scenarios.

• Path: easy-view/
• Purpose: Safely inspect files in the current working directory (the directory where the MCP client starts the server) without editing anything.
• Key behaviours:
  • Builds an index of the workspace using fast-glob, skipping heavy directories (node_modules, .git, dist, build, minified assets) and files larger than 50 MB.
  • Caches the index between calls; invoke scan_directory with refresh: true after large changes.
  • Treats a wide range of extensions as text to provide line counts; binary files are still listed but lines are set to 0.
  • view_file protects against massive outputs by limiting files to 10 MB and lines to 2000 per request.

Usage tips

• Always run scan_directory once per session to prime the index; other tools will call it lazily if needed.
• Patterns for list_files and search_files accept simple wildcards (*, ?); they are converted to regular expressions internally.
• view_file highlights the around_line with a marker so you can quickly spot the target line in context.
• If you add or delete large numbers of files, run scan_directory with refresh: true to keep stats accurate.

• Path: file-download/
• Purpose: Provide a safe place for MCP assistants to persist generated files to the user's machine under ~/.claude/downloads.
• Key behaviours:
  • Creates the downloads directory lazily (~/.claude/downloads) and reuses it across sessions. On Windows this resolves to %USERPROFILE%\.claude\downloads.
  • Sanitises filenames to block path traversal, reserved characters, and leading dots before writing.
  • Supports both UTF-8 text saves and arbitrary binary blobs supplied as base64.
  • Offers listing and deletion helpers so the assistant can manage its outputs explicitly.

Usage tips

• Supply only the intended filename; directories are not permitted and will be flattened during sanitisation.
• save_binary_file rejects invalid base64 strings - validate data before sending.
• Use list_downloads to confirm the file landed as expected before instructing a user to open it.

• Path: ffmpeg-mcp/
• Purpose: Perform advanced video and audio processing using the system-installed FFmpeg binary.
• Key behaviours:
  • Verifies FFmpeg availability before each operation and surfaces stderr output on failures.
  • Supports format conversion, compression, trimming, resizing, merging, watermarking, subtitle burn-in, speed changes, and batch processing.
  • Creates output directories on demand and normalises time parameters (HH:MM:SS or seconds).

Usage tips

• Ensure FFmpeg (and ffprobe) is installed and discoverable via PATH before invoking these tools.
• Provide Windows paths with escaped backslashes in JSON (e.g., C:\\videos\\clip.mp4).
• Long-running operations block until FFmpeg finishes; stream progress to stderr if you need status updates.

• Path: yt-dlp-mcp/
• Purpose: Download media, metadata, and ancillary assets via the yt-dlp downloader.
• Key behaviours:
  • Checks for yt-dlp on the PATH and relays its stderr output when downloads fail.
  • Creates output directories automatically and reports saved filenames in responses.
  • Supports playlists, channels, subtitle/thumbnail downloads, custom format selection, and search.

Usage tips

• Keep yt-dlp updated (yt-dlp -U) to maintain compatibility with streaming sites.
• Use playlist/channel limits to avoid large unattended downloads.
• Escape Windows paths (C:\\Videos\\Downloads) when passing JSON arguments from MCP clients.

• Path: html-mcp/
• Purpose: Parse, inspect, and manipulate HTML documents using Cheerio and jsdom.
• Key behaviours:
  • Accepts either raw HTML strings or file paths (type: "content"/"file") for flexible inputs.
  • Provides selector-based extraction, metadata scraping, form/table inspection, and validation helpers.
  • Supports mutating operations (remove, replace, minify, prettify) with optional file writes.

Usage tips

• Provide absolute paths when using type: "file" so the server can locate the HTML on disk.
• CSS selectors are supported; XPath requests currently throw a validation error.
• Capture the returned HTML or supply savePath when mutating content to persist changes.

• Path: imagemagick-mcp/
• Purpose: Perform image analysis, transformation, and enhancement using ImageMagick CLI tools.
• Key behaviours:
  • Verifies ImageMagick availability before each call and surfaces CLI errors verbatim.
  • Creates output directories on demand and reports generated filenames and size deltas.
  • Supports resizing, cropping, rotation, flipping, format conversion, watermarking, quality tweaks, and batch workflows.

Usage tips

• Install ImageMagick and ensure convert/magick binaries are on your PATH before invoking the tools.
• Escape Windows paths (for example C:\\Images\\photo.jpg) when calling from MCP clients.
• Batch operations process files sequentially; monitor file sizes in responses to gauge compression results.

• Path: json-mcp/
• Purpose: Validate, query, and transform structured data across JSON, YAML, and XML formats.
• Key behaviours:
  • Uses Ajv for JSON Schema validation and returns detailed error metadata.
  • Supports JSONPath queries plus bidirectional conversions between JSON, YAML, and XML.
  • Provides diff and deep-merge helpers for comparing or combining payloads safely.

Usage tips

• Supply compact JSON strings; the server handles parsing before formatting.
• When validating schemas, provide both the instance and schema as JSON strings.
• json_diff returns null when documents match exactly—treat that as "no differences".

• Path: markdown-mcp/
• Purpose: Convert, format, and extract structure from Markdown documents.
• Key behaviours:
  • Leverages marked, turndown, and the Remark ecosystem for reliable Markdown ↔ HTML conversions.
  • Normalises headings, lists, code fences, and emphasis for consistent formatting output.
  • Surfaces document structure by extracting headings, links, images, and table-of-contents markdown.

Usage tips

• extract_toc filters headings deeper than maxDepth; raise it when you need full depth.
• Formatting preserves GitHub Flavoured Markdown extensions (tables, strikethrough, task lists).
• Validation warnings include missing URLs or alt text—surface them to users for cleanup.

• Path: osrs-lookup/
• Purpose: Query Old School RuneScape (OSRS) public APIs for Grand Exchange and player highscore data directly from an assistant session.
• Key behaviours:
  • Wraps the official OSRS endpoints for item categories, item search, detailed listings, price history, and player highscores.
  • Normalises request parameters and validates required inputs (for example, item_id and player_name) before calling the APIs.
  • Returns structured JSON with parsed values (current price, daily averages, skill ranks) so assistants can reason about the results without additional parsing.

Usage tips

• URL-encode player names before passing them if they contain spaces; the server takes care of the rest.
• Use ge_category first to discover available item IDs, then drill down with ge_item_detail or ge_price_graph.
• Highscore lookups require exact display names; check spelling if you see HTTP 404 responses.

• Path: time/
• Purpose: Fetch current times or convert between timezones using IANA zone names.
• Key behaviours:
  • Detects the host timezone via Intl and validates all inputs against the IANA database.
  • Uses Luxon to respect daylight-saving boundaries when performing conversions.
  • Returns structured metadata including day of week and DST state for both source and target zones.

Usage tips

• Provide 24-hour HH:MM inputs for conversions; seconds default to 00.
• Use canonical IANA names such as America/New_York—abbreviations like EST are rejected.
• The conversion response includes the offset delta (e.g., +5h) for quick reference.

• Run npm run dev for quick experiments; it uses ts-node so TypeScript changes take effect immediately (restart the process after edits).
• Run npm run build before shipping or registering the server to guarantee the compiled JavaScript is up to date.
• Use npm run start to execute the compiled build exactly as the client will run it.
• If you need to clear build artefacts on Windows, run powershell -Command "Remove-Item dist -Recurse -Force" instead of npm run clean, or install a cross-platform cleaner (e.g., add rimraf).
• Type definitions live in dist/server.d.ts after building; include them if consuming these servers as libraries elsewhere.

• curl_execute fails with "curl is not recognized": Install curl or add it to the system PATH. On Windows, grab the official installer or enable the optional Windows feature.
• list_files or search_files return nothing: Run scan_directory first or pass { "refresh": true } if you recently changed the workspace.
• view_file reports "File too large": The safety cap is 10 MB. Open the file locally or reduce it before requesting the full content.
• save_binary_file throws "Base64 content is required": Ensure the content string is valid base64 and not JSON-escaped (remove newline characters or wrap in proper JSON).
• npm run clean fails on Windows: Use PowerShell's Remove-Item command or run the script from Git Bash/WSL where rm exists.

Released under the MIT License. You are free to fork, extend, and bundle these servers with your own MCP tooling.