Folk CRM MCP Server
An MCP (Model Context Protocol) server that provides access to Folk CRM functionality, allowing AI assistants to manage contacts, companies, notes, reminders, and more.
Features
- Smart Search: Find people and companies by name with minimal token usage
- Two-Phase Lookup: Quick search returns IDs, then fetch full details as needed
- Contact Management: Create, update, and delete people and companies
- Notes & Reminders: Attach context to your contacts
- Interaction Logging: Track emails, meetings, and calls
Adding to Claude Code
From Registry (Published)
# Configure your Folk API key
mpak config set @nimblebraininc/folk api_key=your_api_key_here
# Add to Claude Code
claude mcp add folk -- mpak run @nimblebraininc/folk
Local Development
# Clone and enter the repo
git clone https://github.com/NimbleBrainInc/mcp-folk.git
cd mcp-folk
# Install dependencies
uv sync
# Build the bundle
make pack
# Configure your API key
mpak config set @nimblebraininc/folk api_key=your_api_key_here
# Add to Claude Code (use absolute path)
claude mcp add folk -- mpak run --local /path/to/mcp-folk/mcp-folk-0.1.0-darwin-arm64.mcpb
Configuration
Getting Your Folk API Key
- Log in to your Folk workspace
- Go to Settings > API
- Create a new API key
- Copy the key and configure with
mpak config set
Available Tools
Search (Use First)
| Tool | Purpose |
|---|---|
find_person(name) | Find people by name, returns {found, matches: [{id, name, email}]} |
find_company(name) | Find companies by name, returns {found, matches: [{id, name, industry}]} |
Details (After Finding)
| Tool | Purpose |
|---|---|
get_person_details(person_id) | Full person info including all fields |
get_company_details(company_id) | Full company info including all fields |
Browse
| Tool | Purpose |
|---|---|
browse_people(page, per_page) | Paginated list of all people |
browse_companies(page, per_page) | Paginated list of all companies |
Groups & Filtering
| Tool | Purpose |
|---|---|
list_groups() | List all groups in the workspace |
find_people_in_group(group_name, status) | Find people in a group, optionally filtered by Status |
find_companies_in_group(group_name, status) | Find companies in a group, optionally filtered by Status |
Actions
| Tool | Purpose |
|---|---|
add_person(first_name, ...) | Create new person |
add_company(name, ...) | Create new company |
update_person(person_id, ...) | Update person fields |
update_company(company_id, ...) | Update company fields |
delete_person(person_id) | Delete a person |
delete_company(company_id) | Delete a company |
Notes & Reminders
| Tool | Purpose |
|---|---|
add_note(person_id, content) | Add note to person |
get_notes(person_id) | Get notes for person |
set_reminder(person_id, reminder, when) | Set a reminder |
log_interaction(person_id, type, when) | Log an interaction |
Utility
| Tool | Purpose |
|---|---|
whoami() | Get current authenticated user |
Common Use Cases
Look up contacts
- "Is Sarah Chen in my CRM?"
- "Find everyone at Acme Corp"
- "What's John's email?"
Add contacts after meetings
- "Add Mike Johnson from today's meeting, he's a PM at Stripe"
- "Create a contact for lisa@example.com"
Take notes
- "Add a note to Sarah: discussed Q2 roadmap, she's interested in enterprise plan"
- "What are my notes on the Acme deal?"
Set follow-ups
- "Remind me to follow up with John next Tuesday"
- "Set a reminder to check in with Sarah in 2 weeks"
Log interactions
- "Log that I had a call with Mike today"
- "Record my meeting with the Acme team"
Browse contacts
- "Show me my recent contacts"
- "List all companies in my CRM"
Query groups and pipelines
- "Show me leads in 'Demos Management' with status 'Follow up 1'"
- "List all people in my Investors group"
- "Find active clients in my Customers group"
- "What groups do I have in Folk?"
Example Flow
User: "I just had coffee with Alex Rivera, she's interested in our API. Remind me to send her docs next week."
AI: find_person("Alex Rivera")
→ {"found": true, "matches": [{"id": "abc123", "name": "Alex Rivera", "email": "alex@techco.io"}]}
AI: add_note("abc123", "Had coffee - interested in API, wants to see docs")
→ {"id": "note456", "added": true}
AI: log_interaction("abc123", "meeting", "2024-01-15T10:00:00Z")
→ {"id": "int789", "logged": true}
AI: set_reminder("abc123", "Send API docs to Alex", "2024-01-22T09:00:00Z")
→ {"id": "rem012", "set": true}
AI: "Done! I've added a note about your coffee chat, logged the meeting, and set a reminder for next Monday to send her the API docs."
Development
# Install dev dependencies
uv sync --dev
# Run tests
uv run pytest tests/ -v
# Format code
uv run ruff format .
# Lint
uv run ruff check .
# Type check
uv run mypy src/
# Run all checks
make check
# Build bundle for testing
make pack
API Reference
This server uses the Folk REST API. Key endpoints:
- Base URL:
https://api.folk.app/v1 - Authentication: Bearer token
- Rate limits apply (see Folk documentation)
License
MIT
