# vCard Contacts Parser MCP

> vCard Contacts Parser converts huge, messy iPhone and Android .vcf exports into clean, queryable JSON. Don't let raw contact files break your AI client or hallucinate data. This tool processes thousands of contacts locally, stripping out binary noise (like profile pictures) and leaving you with structured fields: First Name, Last Name, Organization, Phone, Email.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** vcard, contact-parsing, data-extraction, address-book, json-conversion, file-processing

## Description

You know the drill when you pull contact data off a phone—you get a massive, messy `.vcf` file. These things are full of old `BEGIN:VCARD` junk and useless binary garbage, like base64-encoded profile pics. If your AI client reads that raw mess, it'll choke on context window limits or, worse, start hallucinating phone numbers and emails out of thin air.

This MCP is a dedicated contact intelligence engine. It runs 100% locally, meaning your data never leaves your machine. **It strips away all the binary noise** and converts the raw vCard format into beautiful, easily queryable JSON that your AI client actually understands. When you use `parse_vcard`, it takes that sprawling `.vcf` file and gives you structured fields: First Name, Last Name, Organization, Phone Number, and Email Address.

Need to find someone specific? You can query the entire contact list using the system's search functions; just tell your agent to locate individuals based on their job title or company. The tool doesn't just parse names; it reads every field, accurately differentiating a person’s given name from their family name and pulling out corporate affiliations so you get clean data sets.

If contacts aren't what you need, we got your back for Amazon highlights too. When you use `parse_kindle_clippings`, you feed it the plain text dump from an Amazon Kindle 'My Clippings.txt' export. The tool doesn’t just dump that text; **it structures notes, bookmarks, and highlights** into clean JSON objects, grouping them logically by book title so you know exactly what came from where.

Processing data for a spreadsheet? When the job is done, use the built-in formatting to get your extracted contact records or Kindle clippings formatted for CSV export. This gives you a crisp, comma-separated value file ready to paste straight into any major spreadsheet program. You're not just parsing; you're preparing actionable intelligence.

This server handles huge volumes—it processes vCard files containing thousands of contacts instantly. It keeps everything local for maximum privacy and zero hallucination risk. It ensures perfect extraction of country codes, complex email formats, and specific job titles every single time.

## Tools

### parse_kindle_clippings
Pasting the raw text from a Kindle 'My Clippings.txt' file parses notes and bookmarks into structured JSON, grouping them by book.

## Prompt Examples

**Prompt:** 
```
Search my contacts.vcf and give me a list of everyone who works at 'Vinkius'.
```

**Response:** 
```
I found 3 contacts working at Vinkius: John Silva (DevOps), Sarah Connor (Design), and Mike Ross (Legal).
```

**Prompt:** 
```
Extract all the email addresses from this vCard export and format them as a CSV.
```

**Response:** 
```
Name,Email
Alice Smith,alice@example.com
Bob Jones,bob@example.org
```

**Prompt:** 
```
Look through my contacts and find the phone number for 'Plumber'.
```

**Response:** 
```
The phone number saved under 'Plumber' is +1 (555) 019-8372.
```

## Capabilities

### Extract contact details from vCard files
The tool reads a raw `.vcf` file and outputs structured JSON containing names, organizations, phones, and emails.

### Process Kindle highlights into JSON
It takes the plain text content from an Amazon Kindle 'My Clippings.txt' export and structures notes, bookmarks, and highlights by book title.

### Search contacts by role or company
You can query the entire contact list to find specific individuals based on their job title or employer.

### Format data for CSV export
The tool structures extracted contact records into a clean, comma-separated value format ready for spreadsheets.

## Use Cases

### The Quarterly CRM Cleanup
An Ops Manager receives a massive vCard file from an old client system. Instead of spending hours manually copying names and job titles into a spreadsheet, they ask their agent to run the `vcard-contacts-parser`. The agent returns clean JSON immediately, ready for bulk import.

### The Conference Debrief
A Sales Rep collects dozens of business cards and emails them into a single vCard file. They then use the parser to quickly filter out everyone who doesn't work in their target industry, letting them focus only on qualified leads.

### Organizing Academic Notes
A student finishes reading a textbook and exports all highlights from Kindle into 'My Clippings.txt'. They run the `parse_kindle_clippings` tool, which automatically groups every highlight and note by the book title it came from.

### Identifying Team Members
A project lead needs to know who on the team works at a specific company. They ask their agent: 'Find all contacts working at Acme Corp.' The parser scans the vCard and spits out only those names and titles.

## Benefits

- **Stop context window overflow.** Instead of sending a massive, raw `.vcf` file to your agent—which will chew up tokens and hallucinate—you feed the parser. It returns only clean JSON structured with fields like 'Email' and 'Phone'.
- **Maintain absolute privacy.** Since the parsing happens locally on your machine, your entire address book never leaves your device or hits a third-party server. That's essential for sensitive data.
- **Process massive files easily.** Don't worry about file size. The tool handles VCF exports containing thousands of contacts without breaking or slowing down your workflow.
- **Filter contacts by specific criteria.** Your agent can run direct queries, like 'Find the contact who works at Google,' and get a precise list instead of having to search through every single record manually.
- **Use it for notes too.** While built for vCard data, the tool includes `parse_kindle_clippings`, letting you structure academic or personal notes alongside your professional contacts.

## How It Works

The bottom line is you get structured, usable data without ever uploading your private files to an external server.

1. You point your AI client at the raw file (either a `.vcf` export or Kindle clippings text).
2. The parser runs locally, stripping away all unnecessary binary data and parsing the specific records.
3. Your agent receives a clean JSON array, ready for direct use in prompts: e.g., 'List emails for people at Company X'.

## Frequently Asked Questions

**How does vCard Contacts Parser handle private contacts?**
It handles them by running 100% locally on your machine. Your personal phonebook never leaves your device, ensuring air-gapped privacy.

**Can I use the vCard Contacts Parser for large groups of people?**
Yes. The parser is built to handle VCF files containing 5,000+ contacts without losing data or performance.

**Is there another function besides parsing vCards?**
Yeah. It also includes the `parse_kindle_clippings` tool, letting you structure highlights and notes from Kindle exports into JSON format.

**Does vCard Contacts Parser guarantee accurate phone numbers?**
Yes. Because it parses structured fields directly rather than interpreting raw text, the extraction of country codes and emails is highly precise; hallucination isn't a risk here.

**How does vCard Contacts Parser ensure local privacy when reading my contact files?**
The parser runs 100% locally on your machine. Your personal phonebook never leaves your device; it processes and converts the raw data into JSON without needing to communicate with any external servers.

**When running `vcard-contacts-parser`, how are multiple roles or phone numbers stored in the resulting JSON?**
It handles complex entries by structuring fields as arrays. Instead of overwriting a single field, it creates lists for phones and organizations, ensuring you get every number and title saved accurately.

**How does `parse_kindle_clippings` process my Amazon Kindle highlights?**
It reads the raw text from your 'My Clippings.txt' file and structures it into JSON. This cleanly separates notes, bookmarks, and highlights, grouping them by the original book title for easy querying.

**Is the `vcard-contacts-parser` compatible with various modern or legacy vCard formats?**
Yes. The parser is built to interpret the standard `BEGIN:VCARD` structure used by major platforms. It strips away non-standard binary noise, handling minor format variations effectively.

**Is my address book uploaded to the cloud?**
Never. The vCard parsing is executed completely local on your device. Only the extracted text representation is provided to the AI context.

**Does it support multiple contacts in a single file?**
Yes! It perfectly parses multi-vCard files exported from iOS, Google Contacts, or Android devices, handling thousands of entries seamlessly.

**What happens to the contact profile pictures?**
Profile pictures (PHOTO;ENCODING=b) are intentionally ignored and stripped during parsing to preserve AI context tokens and prevent crashes.