yaniv-golan/affinity-sdk

A modern, strongly-typed Python wrapper for the Affinity CRM API.
Disclaimer: This is an unofficial community project and is not affiliated with, endorsed by, or sponsored by Affinity. “Affinity” and related marks are trademarks of their respective owners. Use of the Affinity API is subject to Affinity’s Terms of Service.
Maintainer: GitHub: yaniv-golan
Documentation: https://yaniv-golan.github.io/affinity-sdk/latest/
Affinity's Official MCP Server
Affinity runs an official MCP Server: a hosted server you connect to from Claude, ChatGPT, Copilot, Notion and other AI clients with OAuth sign-in. It reads and updates most CRM records and is the easiest way to work with Affinity in a chat.
This SDK serves a different purpose — it's a strongly-typed Python client and CLI for the Affinity API (companies, persons, opportunities, lists, field values, notes, reminders, interactions, webhooks, files, and more). Use it when you work with Affinity in code, scripts or a terminal: bulk updates, exports, data pipelines, webhooks, or custom integrations and tooling.
For a detailed comparison, see Affinity SDK vs. Official MCP.
Table of Contents
- Features
- Installation
- Quick Start
- Usage Examples
- Type System
- API Coverage
- Authentication
- Configuration
- Error Handling
- Async Support
- Development
Features
- **Broad API coverage** - V1 and V2, routed per operation (6 V2 operations still planned)
- **CLI included** - Scriptable command-line interface for automation
- **Strong typing** - Full Pydantic V2 models with typed ID classes
- **No magic numbers** - Comprehensive enums for all API constants
- **Automatic pagination** - Iterator support for seamless pagination
- **Rate limit handling** - Automatic retry with exponential backoff
- **Response caching** - Optional caching for field metadata
- **Both sync and async** - Full support for both patterns
AI Integrations
- **Claude Code plugins** - SDK and CLI knowledge for AI-assisted development
- **MCP Server** - Connect desktop AI tools to Affinity
Installation
Requires Python 3.10+.
Optional (local dev): load .env automatically:
Optional: install the CLI:
The CLI includes a powerful query command for structured data extraction with filtering, aggregations, and relationship includes. Output formats include JSON, CSV, markdown, and TOON (token-optimized for LLMs).
CLI docs: https://yaniv-golan.github.io/affinity-sdk/latest/cli/
MCP Server
Connect desktop AI tools to Affinity CRM.
**Claude Desktop** (easiest - MCPB bundle):
1. Install CLI: pipx install "affinity-sdk[cli]"
2. *(Optional)* Pre-configure API key: xaffinity config setup-key
- If skipped, Claude Desktop will prompt for your API key during MCPB install
3. Download the .mcpb bundle from GitHub Releases
4. Double-click to install (or drag to Claude Desktop)
**Other clients** (Cursor, Windsurf, VS Code + Copilot, Zed, etc.):
These require manual configuration. See the MCP Server docs for step-by-step instructions.
MCP docs: https://yaniv-golan.github.io/affinity-sdk/latest/mcp/
Claude Code Plugins
If you use Claude Code, install plugins for SDK/CLI knowledge:
Plugin docs: https://yaniv-golan.github.io/affinity-sdk/latest/guides/claude-code-plugins/
Documentation
- Full documentation
- MCP Server
- CLI Reference
- API Reference
Quick Start
Usage Examples
Working with Companies
Working with Persons
Working with Lists
Notes
Reminders
Files
Webhooks
Rate Limits
Type System
The SDK uses strongly-typed ID classes (int/str subclasses) to prevent accidental mixing:
All magic numbers are replaced with enums:
API Coverage
Which Affinity API the SDK uses for each feature. The SDK uses V2 wherever V2 can do the job and