MCP/mcbluetooth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcbluetooth/docs-site/src/content/docs/guides/phonebook-messages.md
Ryan Malloy 9d1c0f3e0f Add Astro/Starlight documentation site 
23-page docs site following diataxis principles with guides,
reference, and explanation sections covering all 61 MCP tools.
Bluetooth-themed design with Pagefind search.
2026-02-02 14:36:07 -07:00

5.3 KiB
Raw Blame History

title description
Phonebook & Messages Access contacts and SMS using PBAP and MAP profiles

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';

PBAP (Phonebook Access Profile) and MAP (Message Access Profile) let you read contacts and messages from paired phones.

Prerequisites

These profiles use OBEX. Ensure obexd is installed:

bt_obex_status

If not ready:

```bash sudo pacman -S bluez-obex ``` ```bash sudo apt install bluez-obex ```

Phonebook Access (PBAP)

Download Entire Phonebook

bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/contacts.vcf"

This downloads all contacts as a single vCard file.

List Contacts

bt_phonebook_list address="AA:BB:CC:DD:EE:FF"

Returns:

{
  "entries": [
    {"handle": "1.vcf", "name": "Alice Smith"},
    {"handle": "2.vcf", "name": "Bob Jones"},
    ...
  ],
  "count": 150
}

Get Single Contact

bt_phonebook_get address="..." handle="1.vcf" save_path="~/alice.vcf"

Search Contacts

# Search by name
bt_phonebook_search address="..." field="name" value="Smith"

# Search by phone number
bt_phonebook_search address="..." field="number" value="+1555"

Count Contacts

bt_phonebook_count address="AA:BB:CC:DD:EE:FF"

Returns total number of contacts without downloading them.

Phonebook Folders

PBAP provides access to different phonebook locations:

Folder Contents
telecom/pb Main phonebook (default)
telecom/ich Incoming call history
telecom/och Outgoing call history
telecom/mch Missed call history
telecom/cch Combined call history
SIM1/telecom/pb SIM card contacts 
bt_phonebook_list address="..." folder="telecom/ich"

Message Access (MAP)

List Message Folders

bt_messages_folders address="AA:BB:CC:DD:EE:FF"

Returns:

{
  "folders": [
    {"name": "inbox"},
    {"name": "sent"},
    {"name": "drafts"},
    {"name": "outbox"},
    {"name": "deleted"}
  ]
}

List Messages

# All inbox messages
bt_messages_list address="..." folder="inbox"

# Unread only
bt_messages_list address="..." folder="inbox" unread_only=true

# Limit results
bt_messages_list address="..." folder="inbox" max_count=50

Returns:

{
  "messages": [
    {
      "handle": "msg001",
      "subject": "Meeting tomorrow",
      "sender": "+15551234567",
      "timestamp": "2024-01-15T10:30:00",
      "read": false,
      "type": "SMS"
    }
  ]
}

Download Message

bt_messages_get address="..." handle="msg001" save_path="~/message.txt"

Send Message

bt_messages_send address="..." recipient="+15559876543" message="Hello from mcbluetooth!"

Common Workflows

Backup All Contacts

# Download as vCard (can import into any contact app)
bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/phone_backup_$(date +%Y%m%d).vcf"

Export Call History

# Get incoming calls
bt_phonebook_list address="..." folder="telecom/ich"

# Get missed calls
bt_phonebook_list address="..." folder="telecom/mch"

Find Contact by Phone Number

bt_phonebook_search address="..." field="number" value="555-1234"

Archive Text Messages

# List all sent messages
bt_messages_list address="..." folder="sent"

# Download specific message
bt_messages_get address="..." handle="msg042" save_path="~/messages/msg042.txt"

Device Compatibility

PBAP Support

Device Support
Android phones ✓ Full
iPhones ✓ Full (when paired)
Feature phones ✓ Usually
Car systems ✓ Often (receive only)

MAP Support

Device Read Send
Android ✓ Varies
iPhone ✗ ✗
Feature phones Varies Varies

Troubleshooting

"NotAuthorized" Error

The phone is blocking access. Check:

  1. Phone screen for permission prompt
  2. Bluetooth settings → paired device → enable phonebook/message access

Empty Phonebook

Some phones require explicit permission:

  • Android: Settings → Apps → Bluetooth → Permissions → Contacts
  • iPhone: Settings → Bluetooth → [device] → Allow Contact Access

MAP Connection Fails

  1. Verify device supports MAP: bt_device_info adapter="hci0" address="..."
  2. Check for MAP UUID in the UUIDs list
  3. Some devices need MAP enabled in Bluetooth settings

Slow Downloads

Large phonebooks (1000+ contacts) take time:

  • PBAP downloads are sequential
  • Consider using bt_phonebook_count first to estimate
  • vCard format is verbose

Privacy Considerations

  • Phonebook and message access requires active pairing
  • Devices typically prompt for permission on first access
  • Permission can be revoked on the phone at any time