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