---
name: vcard
displayName: vCard (.vcf) Reader & Converter
description: Read and convert vCard .vcf contact files to plain text, JSON, or
  CSV. Use when you need to open, extract, or bulk-export contacts from a .vcf
  file.
tags:
  - document
  - vcard
  - vcf
  - contacts
  - convert
  - extract
capabilities:
  - ReadVcard
  - ConvertToText
  - ConvertToJson
  - ConvertToCsv
  - ExtractContacts
representativeQueries:
  - Read a .vcf file and show me the contacts
  - Convert vcard to CSV
  - Extract contacts from a .vcf file to JSON
  - Parse a vCard file and list all phone numbers and emails
  - Export my .vcf contacts to a spreadsheet-friendly format
version: 0.1.0
tier: curated
---

# vCard (.vcf) Reader & Converter

Reads and converts vCard files (`.vcf`) — the standard contact exchange format used by Apple Contacts, Google Contacts, Outlook, and most phones — to plain text, JSON, or CSV. A single `.vcf` file may contain one contact or thousands; the bundled script handles all three vCard versions (2.1, 3.0, 4.0) using only the Python standard library.

## When to use

- You have a `.vcf` file and need to read or display its contacts.
- You want to export contacts to a spreadsheet (CSV) or a structured format (JSON) for further processing.
- A user asks to "open", "read", "parse", or "convert" a `.vcf` or vCard file.
- You need to extract specific fields — phone numbers, emails, addresses — from a contact file.
- You received a contact export from a phone, mail client, or CRM and want to inspect its contents.

## Steps

1. **Detect format.** Confirm the file has a `.vcf` extension or contains a `BEGIN:VCARD` line. If not, surface a clear error.
2. **Run the converter.** Pass the file path and desired output format (`text`, `json`, or `csv`) to `scripts/vcard_converter.py`.
3. **Unfold and parse.** The script unfolds RFC 6350 line continuations (leading whitespace), joins vCard 2.1 quoted-printable soft-line continuations (lines ending with `=` followed by a line with no leading whitespace), splits on `BEGIN:VCARD` / `END:VCARD` boundaries, and decodes quoted-printable and base64 values as needed.
4. **Handle edge cases.** Binary blobs (PHOTO, LOGO, SOUND, KEY) are omitted from output; a count is noted. Files with mixed vCard versions are processed uniformly.
5. **Inspect output.** Results are printed to stdout; redirect or pipe as needed.

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| `ReadVcard` | READ | contact records from .vcf | `scripts/vcard_converter.py` |
| `ConvertToText` | READ | plain text summary per contact | `scripts/vcard_converter.py --format text` |
| `ConvertToJson` | READ | JSON array of contact objects | `scripts/vcard_converter.py --format json` |
| `ConvertToCsv` | READ | CSV rows with header row | `scripts/vcard_converter.py --format csv` |
| `ExtractContacts` | READ | structured field extraction | `scripts/vcard_converter.py --format json` |

## Output

- **text**: one block per contact with labelled fields (Name, Phone, Email, etc.) separated by blank lines, written to stdout.
- **json**: a JSON array of objects; each object has keys `full_name`, `first_name`, `last_name`, `phones`, `emails`, `addresses`, `organization`, `title`, `birthday`, `note`, `urls`, and `other` (a dict of remaining properties).
- **csv**: UTF-8 comma-separated rows with a header; columns are `full_name`, `first_name`, `last_name`, `organization`, `title`, `phones`, `emails`, `addresses`, `birthday`, `urls`, `note`. Multi-value fields are joined with ` | `.

## Notes

- The bundled script requires **only the Python standard library** — no `pip install` needed.
- vCard 2.1 files are common in exports from older Android and Nokia devices; they use quoted-printable encoding and may omit `VERSION:`.
- Large `.vcf` exports (e.g. Google Takeout) can contain thousands of contacts and megabytes of base64-encoded photos. The script skips binary blob properties (PHOTO, LOGO, SOUND, KEY) and reports a count of skipped fields in the `text` format output. JSON and CSV outputs omit the count (binary blobs are silently excluded).
- Line endings: vCard spec requires CRLF, but many files use LF only. The script normalises both.
- If a contact has no `FN` (formatted name) field, the script reconstructs a name from `N` (structured name) components.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `vcard_to_text`, `vcard_to_json`, `vcard_to_csv`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).