\n\n \n\n> **Kitbag MCP** is a single, open-source [Model Context Protocol](https://modelcontextprotocol.io) server that bundles a curated library of **50+ high-value utility tools** β document converters, OCR processors, web scrapers, data formatters, and AI developer utilities β all in one place.\n>\n> Instead of installing, configuring, and paying to host a dozen single-purpose MCP servers, install **Kitbag MCP once** and selectively enable only the modules you need. It runs entirely on your machine: **zero hosting costs**, **no API keys**, **no server setup**.\n\n
\n\n\n\n\n
\n\n---\n\n## π Table of Contents\n\n\nClick to expand\n\n- [π Quick Start](#-quick-start-zero-config)\n- [βοΈ Client Setup](#οΈ-supported-clients-setup)\n - [Claude Desktop](#1-claude-desktop)\n - [Cursor](#2-cursor)\n - [Windsurf](#3-windsurf)\n- [ποΈ Configuration](#οΈ-configuration-flags--environment-variables)\n- [πΊοΈ Tool Category Index](#οΈ-tool-category-index)\n- [π Complete Tool Directory](#-complete-tool-directory)\n - [π PDF Tools](#-pdf-tools-pdf)\n - [π Web Scraping & Networking](#-web-scraping--networking-web)\n - [πΈ Image & OCR Tools](#-image--ocr-tools-image)\n - [π Data Transformation](#-data-transformation-data)\n - [π» Developer Utilities](#-developer-utilities-developer)\n - [π οΈ Utility Tools](#οΈ-utility-tools-utility)\n - [π§ AI Chunker](#-ai-chunker-ai)\n- [ποΈ Architecture](#οΈ-how-it-works)\n- [π οΈ Local Development & Contributions](#οΈ-local-development--contributions)\n- [βοΈ License](#οΈ-license)\n\n\n\n---\n\n## π Quick Start (Zero Config)\n\nRun instantly using `npx` (Node.js required):\n\n```bash\nnpx kitbag-mcp\n```\n\n### Expose Specific Modules (Saves LLM Context Tokens)\n\nTo prevent your AI agents from getting overwhelmed by tool options, enable only what you need:\n\n```bash\n# Enable PDF and Web scraping modules only\nnpx kitbag-mcp --enabled-modules pdf,web\n```\n\n
\n β\n β\n β\n\n
\n\n---\n\n## βοΈ Supported Clients Setup\n\n### 1. Claude Desktop\n\nAdd this entry to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"kitbag-mcp\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"kitbag-mcp\",\n \"--enabled-modules\",\n \"pdf,web,image,data,utility,ai\"\n ]\n }\n }\n}\n```\n\n### 2. Cursor\n\n1. Go to **Settings** β **Beta Features** β **MCP**.\n2. Click **+ Add New MCP Server**.\n3. Configure:\n - **Name**: `Kitbag MCP`\n - **Type**: `stdio`\n - **Command**: `npx -y kitbag-mcp --enabled-modules pdf,web,data,utility`\n\n### 3. Windsurf\n\nAdd this entry to your `mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"kitbag-mcp\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"kitbag-mcp\"\n ],\n \"env\": {\n \"KITBAG_ENABLED_MODULES\": \"pdf,web,data,utility\"\n }\n }\n }\n}\n```\n\n---\n\n## ποΈ Configuration Flags & Environment Variables\n\nKitbag MCP can be configured through CLI flags, environment variables, or a JSON config file β whichever fits your workflow.\n\n| Configuration Source | Example Usage |\n| :--- | :--- |\n| **CLI Flags** | `--enabled-modules pdf,web` or `--enabled-tools utility.qr_generate` |\n| **Env Variables** | `KITBAG_ENABLED_MODULES=pdf,web` or `KITBAG_ENABLED_TOOLS=utility.qr_generate` |\n| **JSON Config** | A `kitbag-config.json` file in the current working directory, or via `--config /path/to/config.json` |\n\n**`kitbag-config.json` schema:**\n\n```json\n{\n \"enabledModules\": [\"pdf\", \"web\", \"image\", \"data\", \"utility\", \"ai\", \"developer\"],\n \"enabledTools\": [],\n \"defaultTimeoutMs\": 30000,\n \"maxPayloadSizeBytes\": 52428800\n}\n```\n\n---\n\n## πΊοΈ Tool Category Index\n\n
\n\n---\n\n## π Complete Tool Directory\n\n### π PDF Tools (`pdf.*`)\n\nHigh-performance local PDF parsers and manipulators.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `pdf.convert_to_text` | Extract raw text from a PDF document. | *\"Extract the text from reports/invoice.pdf\"* |\n| `pdf.convert_to_markdown` | Parse PDF and format it into clean Markdown. | *\"Convert layout of guide.pdf to markdown\"* |\n| `pdf.extract_images` | Extract raw image assets embedded inside a PDF. | *\"Extract all images from slide_deck.pdf\"* |\n| `pdf.extract_tables` | Extract structured table data from PDF pages. | *\"Pull out all tables from financial_report.pdf\"* |\n| `pdf.merge` | Merge multiple PDF files together in order. | *\"Merge doc1.pdf and doc2.pdf into a single file\"* |\n| `pdf.split` | Split specific page ranges from a PDF. | *\"Give me page 1 to 3 from main_guide.pdf\"* |\n\n---\n\n### π Web Scraping & Networking (`web.*`)\n\nInteract with raw web documents and query networking systems.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `web.to_markdown` | Scrape a webpage, clean clutter, and convert to Markdown. | *\"Convert the article at https://example.com/blog to markdown\"* |\n| `web.extract_metadata` | Extract title, description, OG tags, and JSON-LD data. | *\"Get metadata for URL https://news.ycombinator.com\"* |\n| `web.extract_links` | Scrape a webpage and list internal and external links. | *\"Find all external links on the Wikipedia page for AI\"* |\n| `web.rss_parser` | Parse an RSS or Atom feed XML URL into JSON. | *\"Get the latest feed items from https://github.blog/feed/\"* |\n| `web.sitemap_generator` | Fetch and parse a sitemap.xml URL, extracting all URLs. | *\"Fetch all URLs in the sitemap for google.com\"* |\n| `web.dns_lookup` | Perform DNS resolution (A, AAAA, MX, TXT, etc.). | *\"Do an MX record lookup for domain gmail.com\"* |\n| `web.youtube_transcript` | Extract text transcripts and captions with timestamps. | *\"Get the transcript for https://www.youtube.com/watch?v=dQw4w9\"* |\n\n---\n\n### πΈ Image & OCR Tools (`image.*`)\n\nManipulate images and extract text locally.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `image.ocr` | Extract text from an image locally using Tesseract OCR. | *\"Extract text from screenshot.png\"* |\n| `image.resize` | Resize an image's dimensions (width and height). | *\"Resize avatar.png to be 200x200 pixels\"* |\n| `image.compress` | Compress image file size with custom quality. | *\"Compress banner.jpg to 80% quality\"* |\n| `image.convert_format`| Convert images between formats (PNG, JPEG, WebP, etc.). | *\"Convert logo.png to webp format\"* |\n| `image.exif_metadata` | Extract EXIF camera and location metadata from image files. | *\"Show me the GPS coordinates and camera model of photo.jpg\"* |\n\n---\n\n### π Data Transformation (`data.*`)\n\nFast, offline conversion between standard data formats.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `data.csv_to_json` | Convert CSV file or raw text to JSON. | *\"Parse users.csv and return it as JSON\"* |\n| `data.json_to_csv` | Convert JSON array of objects to CSV output. | *\"Convert this array of users to a CSV table\"* |\n| `data.xml_to_json` | Convert XML documents to structured JSON objects. | *\"Convert this configuration XML text to JSON\"* |\n| `data.json_to_xml` | Convert JSON objects to clean XML output. | *\"Export this JSON object into XML tag format\"* |\n| `data.yaml_to_json` | Convert YAML documents to JSON. | *\"Convert Kubernetes config yaml to JSON\"* |\n| `data.json_to_yaml` | Convert JSON objects to clean YAML format. | *\"Format this database JSON block as YAML\"* |\n| `data.deduplicate` | Deduplicate arrays of JSON objects by a specific key. | *\"Remove duplicates from this list of user objects by ID\"* |\n| `data.diff_arrays` | Compare two JSON arrays and list differences. | *\"Compare array A and B and show me additions and removals\"* |\n\n---\n\n### π» Developer Utilities (`developer.*`)\n\nStandard formats, validation, and layout tools for developers.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `developer.json_formatter`| Format and prettify JSON strings with custom indentation. | *\"Prettify this JSON string using 4 spaces indent\"* |\n| `developer.jwt_decoder` | Decode JWT tokens to read payload/header claims. | *\"Decode this JWT token: eyJhbGciOiJI...\"* |\n| `developer.sql_formatter` | Format SQL strings for multiple database dialects. | *\"Format this messy select query for PostgreSQL\"* |\n| `developer.mermaid_generate`| Create Mermaid diagrams (flowcharts, sequence, etc.). | *\"Generate a flowchart diagram representing this user flow\"* |\n| `developer.openapi_parser`| Parse and format OpenAPI/Swagger specification files. | *\"List the endpoints and request schemas of this openapi.yaml\"* |\n| `developer.regex_tester` | Test regular expression matches on text. | *\"Test if this email regex matches test@example.com\"* |\n| `developer.cron_parser` | Parse Cron expressions and list upcoming execution times. | *\"Tell me when the cron job '0 9 * * 1-5' runs next\"* |\n| `developer.diff_files` | Show line differences between text files. | *\"Show me the diff between fileA.txt and fileB.txt\"* |\n| `developer.diff_json` | Show differences between JSON schemas. | *\"Highlight structural changes between config1.json and config2.json\"* |\n| `developer.code_detector` | Detect programming language and syntax structure. | *\"What programming language is this code written in?\"* |\n| `developer.markdown_lint` | Lint and validate formatting in Markdown files. | *\"Find styling errors or trailing spaces in index.md\"* |\n\n---\n\n### π οΈ Utility Tools (`utility.*`)\n\nSystem, network, and cryptography helper functions.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `utility.qr_generate` | Generate a QR code as a file or base64 Data URL. | *\"Create a QR code pointing to https://github.com\"* |\n| `utility.qr_read` | Read and decode a QR code from a file or stream. | *\"What does the QR code inside code.png say?\"* |\n| `utility.base64_encode` | Convert strings/files to base64 format. | *\"Base64 encode the string 'Hello World'\"* |\n| `utility.base64_decode` | Decode base64 strings back to text. | *\"Decode 'SGVsbG8gV29ybGQ='\"* |\n| `utility.uuid_generate` | Generate secure UUIDs (v4/v1) or secure passwords. | *\"Generate a secure password of length 16\"* |\n| `utility.file_hash` | Compute md5, sha1, or sha256 hashes of text/data. | *\"Calculate the sha256 hash of this string\"* |\n| `utility.email_validate` | Validate syntax and verify MX records of emails. | *\"Check if support@github.com has valid MX records\"* |\n| `utility.ssl_check` | Query certificate expiration date and info for any domain. | *\"Check when the SSL certificate for google.com expires\"* |\n| `utility.unit_convert` | Convert values between physical or data units. | *\"Convert 1024 megabytes to gigabytes\"* |\n| `utility.url_parser` | Break down URLs into protocol, domain, params, etc. | *\"Parse this search query URL into its components\"* |\n| `utility.zip_create` | Compress files or folders into a single ZIP archive. | *\"Compress source/ and assets/ into workspace.zip\"* |\n| `utility.zip_extract` | Extract a ZIP archive to a destination folder. | *\"Extract files from archive.zip into build_dir/\"* |\n\n---\n\n### π§ AI Chunker (`ai.*`)\n\nSegment large text structures dynamically for ingestion.\n\n| Tool Name | Description | Example Agent Prompt |\n| :--- | :--- | :--- |\n| `ai.text_chunker` | Chunk long text using paragraph/sentence/word strategies. | *\"Chunk this text document into 500-char sizes with a 50-char overlap\"* |\n\n---\n\n## ποΈ How It Works\n\n```mermaid\nflowchart LR\n A[AI Agent / Client] -->|MCP Protocol| B(Kitbag MCP Server)\n B --> C{Enabled Modules}\n C --> D[π pdf.*]\n C --> E[π web.*]\n C --> F[πΈ image.*]\n C --> G[π data.*]\n C --> H[π» developer.*]\n C --> I[π οΈ utility.*]\n C --> J[π§ ai.*]\n D & E & F & G & H & I & J --> K[Local Execution No External API Calls]\n K --> A\n```\n\nKitbag MCP runs as a single local process. Your AI client talks to it over the standard MCP protocol, and only the modules you enable are exposed as tools β keeping token usage low and your workflow fast and private.\n\n---\n\n## π οΈ Local Development & Contributions\n\nEvery tool is fully self-contained. Adding a new tool is as simple as creating a folder inside `src/tools///`.\n\n### Contribution Requirements\n\n| File | Purpose |\n| :--- | :--- |\n| `tool.ts` | The main execution code, exporting a `ToolDefinition`. |\n| `README.md` | Direct tool documentation and parameter descriptions. |\n| `example.json` | Sample inputs and expected outputs. |\n| `tests.ts` | Self-contained unit tests using mocks where necessary to run instantly. |\n\n### Command Guide\n\n```bash\n# Build compiler output\nnpm run build\n\n# Run all 50 module tests\nnpm test\n\n# Run real-life execution checks (makes live API and DNS requests)\nnpx tsx src/tests/run_real_life.ts\n```\n\n
\n\n\n\n
\n\n---\n\n## βοΈ License\n\nDistributed under the **MIT License**. See [`LICENSE`](./LICENSE) for more information. Fully open-source and free to adapt for personal or commercial use.\n\n
\n\n\n\n**β If Kitbag MCP saves you time, consider starring the repo! β**\n\n
![\"CI\"/](\"https://github.com/syedtaj7/Kitbag-mcp/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n\n\n ![\"npm](\"https://img.shields.io/npm/v/kitbag-mcp?logo=npm&color=CB3837&label=npm\")
\n\n\n ![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n\n\n ![\"Platform](\"https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-blue\"){kind=icon}
\n\n\n ![\"Model](\"https://img.shields.io/badge/MCP-1.0.0-orange\"){kind=icon}
\n\n![\"downloads\"/](\"https://img.shields.io/npm/dt/kitbag-mcp?color=success&label=downloads\")
\n![\"stars\"/](\"https://img.shields.io/github/stars/syedtaj7/Kitbag-mcp?style=social\")
\n![\"last](\"https://img.shields.io/github/last-commit/syedtaj7/Kitbag-mcp?color=blueviolet\")
\n\n![](\"https://img.shields.io/badge/-No%20API%20Keys-2ea44f?style=for-the-badge\"){kind=icon}
\n![](\"https://img.shields.io/badge/-Zero%20Hosting%20Cost-2ea44f?style=for-the-badge\"){kind=icon}
\n![](\"https://img.shields.io/badge/-Runs%20Locally-2ea44f?style=for-the-badge\"){kind=icon}
\n![](\"https://img.shields.io/badge/-Zero%20Config-2ea44f?style=for-the-badge\"){kind=icon}
\n![](\"https://img.shields.io/badge/Step%201-Install-6C63FF?style=flat-square\"){kind=icon}
β\n![](\"https://img.shields.io/badge/Step%202-Choose%20Modules-6C63FF?style=flat-square\"){kind=icon}
β\n![](\"https://img.shields.io/badge/Step%203-Connect%20Client-6C63FF?style=flat-square\"){kind=icon}
β\n![](\"https://img.shields.io/badge/Step%204-Start%20Using-2ea44f?style=flat-square\"){kind=icon}
\n![](\"https://img.shields.io/badge/-Report%20a%20Bug-red?style=for-the-badge&logo=github\"){kind=icon}
\n![](\"https://img.shields.io/badge/-Submit%20a%20PR-brightgreen?style=for-the-badge&logo=github\"){kind=icon}
\n![](\"https://img.shields.io/badge/-Start%20a%20Discussion-blueviolet?style=for-the-badge&logo=github\"){kind=icon}
\n