xaffinity MCP
MCP server for Affinity CRM - entity search, relationship intelligence, and workflow management
★ 0MITsearch
Install
Config snippet generator goes here (5 client tabs)
README
# Affinity Python SDK [](https://github.com/yaniv-golan/affinity-sdk/actions/workflows/ci.yml) [](https://codecov.io/gh/yaniv-golan/affinity-sdk) [](https://pypi.org/project/affinity-sdk/) [](https://pypi.org/project/affinity-sdk/) [](https://opensource.org/licenses/MIT) [](https://mypy-lang.org/) [](https://docs.pydantic.dev/) [](https://yaniv-golan.github.io/affinity-sdk/latest/) [](https://yaniv-golan.github.io/affinity-sdk/latest/mcp/) [](https://github.com/yaniv-golan/mcp-bash-framework) [](https://yaniv-golan.github.io/affinity-sdk/latest/guides/claude-code-plugins/) A modern, strongly-typed Python wrapper for the [Affinity CRM API](https://api-docs.affinity.co/). 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 As of March 2026, Affinity has released an [official MCP Server (beta)](https://developer.affinity.co/pages/mcp/introduction) for conversational, natural-language access to your CRM data via AI chat clients. It covers relationship intelligence queries, pipeline summaries, meeting activity, and note capture. This SDK serves a different purpose — it's a full-coverage, strongly-typed Python client for the Affinity API, supporting the complete read/write surface (companies, persons, lists, field values, notes, reminders, webhooks, files, and more). Use it when you need programmatic control, write operations, type safety, or want to build custom integrations and tooling. For a detailed comparison, see [Affinity SDK vs. Official MCP](https://yaniv-golan.github.io/affinity-sdk/latest/guides/affinity-official-mcp-comparison/). ## Table of Contents - [Features](#features) - [Installation](#installation) - [Quick Start](#quick-start) - [Usage Examples](#usage-examples) - [Type System](#type-system) - [API Coverage](#api-coverage) - [Configuration](#configuration) - [Error Handling](#error-handling) - [Async Support](#async-support) - [Development](#development) ## Features - **Complete API coverage** - Full V1 + V2 support with smart routing - **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 ```bash pip install affinity-sdk ``` Requires Python 3.10+. Optional (local dev): load `.env` automatically: ```bash pip install "affinity-sdk[dotenv]" ``` Optional: install the CLI: ```bash pipx install "affinity-sdk[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](https://github.com/yaniv-golan/affinity-sdk/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](https://yaniv-golan.github.io/affinity-sdk/latest/mcp/) for step-by-ste