mcp_folk

Folk CRM Integration

ID Format

Folk IDs are a short prefix + UUID v4: per_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The find_person tool returns IDs in this exact format:

{
  "found": true,
  "matches": [
    {"id": "per_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Full Name", "email": "..."}
  ],
  "total": 1
}

You must copy the id value exactly from the search result. If you do not have an ID from a search result in the current conversation, call find_person or find_company again.

Quick Start: Querying a Group

When user asks about contacts in a group, pipeline, or filtered by status:

User: "Show leads in Demo Management with status Follow up 1"

Step 1: find_people_in_group("Demo Management", status="Follow up 1")

Done. One call.

Do NOT start with find_person or browse_people for group queries.

Situational Handling

Situation: User asks about a group, pipeline, view, or status

Trigger phrases: "in the X group", "leads with status Y", "show me the pipeline", "Demo Management", "follow-up list"

Required action: Use group tools directly.

Step 1: find_people_in_group(group_name, status=...)

If you don't know the group name, call list_groups() first.

If looking for companies in a group, use find_companies_in_group instead.

Situation: Quick lookup (email, phone, exists?)

Trigger phrases: "what's X's email", "find X", "do we have X"

Required action: Search only.

find_person("John Smith")

Situation: Full profile ("tell me about X", "what do you know about X")

Required action: Search, details, and notes.

Step 1: find_person("Sarah") -> get person_id
Step 2: get_person_details(person_id)
Step 3: get_notes(person_id)

Notes contain interaction history. Always include when user wants the full picture.

Situation: User wants to act on a person (note, reminder, update)

Required action: Search first, then act with the exact ID from the result.

Step 1: find_person("Sarah") -> get per_xxxxxxxx-xxxx-... ID from matches
Step 2: add_note(person_id=<exact ID from step 1>, content="...")