folk-crm

Folk CRM MCP Server

MCP server for interacting with Folk CRM API. Provides 16 tools for managing people, companies, groups, and notes through any MCP-compatible client.

Installation

1. Clone and install dependencies:

git clone https://github.com/fuego-wtf/folk-mcp.git
cd folk-mcp
pip install -r requirements.txt

1. Create .env file with your API key:

cp .env.example .env
# Edit .env and add your Folk API key

Get your API key from: https://folk.app/settings/developers

Configuration

Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "folk-crm": {
      "command": "python",
      "args": ["/path/to/folk-mcp/server.py"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "folk-crm": {
      "command": "python",
      "args": ["/path/to/folk-mcp/server.py"],
      "env": {
        "FOLK_API_KEY": "your_api_key_here"
      }
    }
  }
}

If using .env file, you can omit the env block.

Available Tools (16 total)

People

| Tool | Description | |------|-------------| | folk_search_people | Search for people by name, email, company | | folk_get_person | Get full person details | | folk_create_person | Create person with emails, companies, groups | | folk_update_person | Update person fields, companies, groups | | folk_delete_person | Delete a person |

Companies

| Tool | Description | |------|-------------| | folk_search_companies | Search companies by name | | folk_get_company | Get full company details | | folk_create_company | Create company with groups | | folk_update_company | Update company fields, groups |

Groups

| Tool | Description | |------|-------------| | folk_list_groups | List all groups/lists | | folk_get_group_members | Get members of a group | | folk_add_to_group | Add person to a group | | folk_remove_from_group | Remove person from a group | | folk_export_group | Export group as CSV or JSON |

Notes

| Tool | Description | |------|-------------| | folk_add_note | Add a note to a person |

Key Features

• Company linking — Associate people with companies on create or update
• Group management — Add people/companies to groups with object-format IDs
• Retry logic — Automatic retry with exponential backoff for transient failures
• Rate limit handling — Respects Retry-After header on 429 responses
• Input validation — All IDs validated before API calls
• Pagination — Cursor-based pagination for large result sets
• CSV export — Proper escaping via Python csv module

Usage Examples

Link a person to a company

Update person per_xxx in Folk — set their company to Graphyn (com_yyy)

Create a contact with company

Create a new person in Folk: Jane Doe, jane@example.com, linked to company "Acme Corp"

Search and export

Export the "Potential Investors" group from Folk as CSV

Add to a group

Add person per_xxx to the "Komunite" group in Folk

Security

• API keys loaded from .env file (never committed)
• All IDs validated with regex patterns before API calls
• Rate limiting respected with automatic backoff

Folk API Documentation

For more details on the Folk API: https://developers.folk.app/

License

MIT