# vCard Contacts Parser Extended MCP

> vCard Contacts Parser Extended instantly converts massive iPhone and Android .vcf exports into clean, structured JSON. This tool bypasses the context window limits of raw vCard data, delivering a reliable address book that your AI client can query directly for names, emails, phone numbers, and company roles.

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

## Description

When you pull contacts off your phone, what do you get? You get a vCard (`.vcf`) file. These things are garbage—they’re bloated messes stuffed with binary noise, base64-encoded images, and decades of legacy data structures like `BEGIN:VCARD`. If you just throw that raw export at an LLM or your agent, it wastes tokens trying to parse irrelevant junk or, worse, it starts hallucinating fields because the data is too messy. You need something dedicated.

The **vCard Contacts Parser Extended** handles this garbage and gives you usable intel. This tool's sole job is to take a file path pointing to a vCard export and convert that raw chaos into clean, structured JSON. Your AI client doesn't see the mess; it only sees what matters: actionable data points.

The core functionality lives in `parse_vcard_contacts`. When you run this tool, it reads the vCard file path and immediately strips away all the binary noise and structural overhead. It processes those messy contacts and outputs a perfectly structured JSON array ready for querying. You're getting raw contact data organized into predictable fields, which is exactly what your agent needs to work with.

Structuring Raw Contacts: The tool takes that volatile vCard file path and turns it into an easily queryable JSON format. This isn't just dumping the text; it’s parsing a massive array of contacts, ensuring every entry follows the same clean data schema. You get back structured contact details you can immediately work with.

Extracting Key Data Points: The parser doesn't just dump everything it finds. It isolates and organizes the specific fields that actually matter for business use. Think about it: phone numbers, email addresses, full names, company roles—it pulls them out individually. This granularity means your agent can reliably check if a contact has an office number versus a mobile number, or separate their first name from their last name without fail.

Handling Large Datasets: This is where the tool really shines. If you have thousands of contacts—like exporting an entire corporate directory that's loaded with data—the parser handles it. It processes these huge vCard files containing potentially thousands of entries without hitting context window limits or slowing down. You can pass in a gigantic file, and it reliably delivers structured JSON for every single contact.

The output is designed for machine readability. Instead of dealing with cryptic headers and semi-colon separated garbage, your agent gets pure data. It's perfect for tasks like generating mailing lists, cross-referencing client records, or populating databases in batches.

When you use `parse_vcard_contacts`, you’re essentially giving your AI client a clean API endpoint for contact intelligence. You provide the file path; it returns an array of objects, where each object is one perfectly parsed contact record. These records reliably contain separated fields for: **names** (first and last), **phone numbers**, **email addresses**, and detailed **organization information**. The JSON format makes querying straightforward—your agent doesn't have to guess which field holds the primary phone number; it just looks at `contact[].phone_number`.

The efficiency of this process saves time. You don't waste compute cycles trying to decipher legacy data formats. Instead, your agent uses those resources doing actual work, like drafting follow-up emails or checking for duplicate entries across multiple client lists.

## Tools

### parse_vcard_contacts
Reads a vCard file path and converts the raw contacts into structured JSON, extracting names, phones, emails, and organization details.

## 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

### Structure Raw Contacts
Parses a vCard file path into an easily queryable JSON array containing extracted contact details.

### Extract Key Data Points
Isolates and organizes specific fields like phone numbers, email addresses, names, and company roles from the raw data.

### Handle Large Datasets
Processes vCard files containing thousands of contacts without context window overflow.

## Use Cases

### Updating a CRM with field sales leads
A salesperson collects 300 new contacts in messy vCard format. Instead of manually entering them, they point their agent to the file and use `parse_vcard_contacts`. The tool delivers structured JSON that updates all necessary fields (Name, Company, Phone) automatically.

### Generating a Marketing Email List
A marketing team needs emails for everyone who works at 'Vinkius'. They run `parse_vcard_contacts` on the master export. The resulting JSON allows their agent to filter all records by Organization and output a clean, CSV-ready list of email addresses.

### Quickly Finding an Old Colleague's Info
A user needs the direct number for 'Plumber'. They use `parse_vcard_contacts` on their contacts. The agent then searches the resulting structured data and reports back: 'The phone number saved under Plumber is +1 (555) 019-8372.' No searching through raw text is needed.

### Bulk Data Validation
A developer gets a vCard file containing mixed data. They run `parse_vcard_contacts` to ensure every field (email, phone) exists and is correctly formatted before the data hits their production database.

## Benefits

- Eliminates hallucination. When your agent runs `parse_vcard_contacts`, it extracts validated country codes, company names, and email formats accurately—no guesswork required.
- Handles massive volumes. Process VCF files with 5,000+ contacts in a single call without hitting context window limits or slowing down the workflow.
- Maintains privacy. Since this MCP runs locally, your personal phonebook never leaves your machine, keeping sensitive contact data air-gapped.
- Saves tokens and time. Instead of feeding gigabytes of messy vCard text to your AI client (which wastes tokens), you feed it a clean JSON object, making every query cheaper and faster.
- Directly queryable. Your agent can ask, 'Find the phone number for the CTO' after using `parse_vcard_contacts`, turning unstructured data into immediate answers.

## How It Works

The bottom line is: it turns a messy phone backup file into reliable, consumable JSON data that your agent can use without hallucinating.

1. You provide the tool with the absolute file path to your raw `.vcf` contact export.
2. The MCP Server executes `parse_vcard_contacts`, which runs locally on your machine, stripping out all binary and structural noise.
3. Your AI client receives a clean JSON array. This structured data is immediately ready for querying by name or role.

## Frequently Asked Questions

**How does vCard Contacts Parser Extended handle large files?**
It processes massive VCF files (5,000+ contacts) without context window overflow. The local parsing mechanism handles the volume before passing the clean data to your AI client.

**Is vCard Contacts Parser Extended secure for private contacts?**
Yes. This MCP runs 100% locally on your machine, meaning your personal phonebook never leaves your system or gets sent over the internet.

**What fields does parse_vcard_contacts guarantee extraction?**
It reliably extracts First Name, Last Name, Organization, Phone Number, and Email Address. It converts these into distinct JSON fields ready for use.

**Can I run vCard Contacts Parser Extended on iPhone or Android exports?**
Yes. Since it reads the standard `.vcf` format, it handles exports from both major mobile platforms reliably.

**What happens if I run `parse_vcard_contacts` with a malformed or corrupted vCard file?**
The tool handles errors gracefully. If the input file has bad entries, it skips the corrupt records and outputs structured JSON for all valid contacts found. You don't lose data just because one record is damaged.

**After running `parse_vcard_contacts`, can I convert the output JSON into CSV format?**
Yes, you can easily do that. The tool outputs clean, structured JSON which your AI client then processes to create a CSV file. You just ask your agent to transform the resulting data structure.

**Does `parse_vcard_contacts` require any API keys or external authentication?**
No credentials are needed. Since this MCP runs 100% locally on your machine, it doesn't touch external APIs or require user sign-in. Your data never leaves your device.

**How does `parse_vcard_contacts` handle non-English characters or special symbols in names?**
It correctly processes Unicode encoding for international characters. You won't lose accents, unique scripts, or other non-Latin characters from foreign contacts.

**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.