xaffinity MCP

xaffinity MCP Server

An MCP (Model Context Protocol) server for Affinity CRM, built with the MCP Bash Framework.

Features

• Entity Management - Search and lookup persons, companies, and opportunities
• Workflow Management - View and update pipeline status, manage list entries
• Relationship Intelligence - Get relationship strength scores and find warm intro paths
• Interaction Logging - Log calls, meetings, emails, and messages
• Session Caching - Efficient caching to minimize API calls

Quick Start

# 1. Install the xaffinity CLI

pipx install "affinity-sdk[cli]"

2. (Optional) Configure your API key - Claude Desktop will prompt if skipped

xaffinity config setup-key

3. Install the MCP server (choose one)

- Claude Desktop: Download and double-click xaffinity-mcp-*.mcpb

- Other clients: See "Manual Installation" below

- Claude Code: /plugin marketplace add yaniv-golan/affinity-sdk

Prerequisites

For Claude Desktop / MCPB Installation (Recommended)

The .mcpb bundle is self-contained — it includes the MCP Bash Framework and gojq. You only need:

Keep the CLI and the extension in step. They are installed separately. When you upgrade one, upgrade the other: download the latest .mcpb after pipx upgrade affinity-sdk, and the other way round. Since MCP 1.25.2, with a CLI older than the extension needs, changes are refused ("This MCP server needs the xaffinity CLI … or later to make changes") and reads still run with a warning that results may be incomplete. An older extension with a newer CLI can fail without saying why (for example, merges with CLI 1.22.0 need extension 1.25.1 or later). Claude Desktop never updates an extension installed from a .mcpb file: install each new release yourself.

For Manual Installation

Manual installation requires additional dependencies:

Installing jq/gojq

Either jq or gojq works — the server auto-detects which is available.

Which to choose:

• jq (recommended) — The original, widely available, full regex support
• gojq — Pure Go implementation, also supports YAML, better error messages

Install jq:

Install gojq (alternative):

Installation

Option 1: Claude Desktop (One-Click)

The .mcpb bundle is fully self-contained — it includes the MCP framework and JSON processor.

1. Install the xaffinity CLI: pipx install "affinity-sdk[cli]"
2. *(Optional)* Configure your API key: xaffinity config setup-key

• If skipped, Claude Desktop will prompt for your API key during MCPB installation

1. Download xaffinity-mcp-*.mcpb from the latest release
2. Double-click the file or drag it into Claude Desktop

Note: MCPB bundles currently only work with Claude Desktop. Other clients require manual installation.

Option 2: Claude Code

/plugin marketplace add yaniv-golan/affinity-sdk

/plugin install affinity-crm-mcp-unofficial@xaffinity

Option 3: Manual Installation

For other MCP clients or development. Requires additional prerequisites.

1. Download xaffinity-mcp-plugin.zip from the latest release
2. Extract and configure your MCP client (see Usage below)
3. The MCP Bash Framework runtime is vendored in .mcp-bash/ — no separate install needed to run the server.
4. Optional — validate your configuration. validate and doctor are developer tools that need the full mcp-bash install (the vendored copy is runtime-only); the command prints the install line for the pinned version if it is missing:

   ./xaffinity-mcp.sh validate

Troubleshooting

Verify Installation

Before debugging, verify each layer works in order:

Step 1: CLI Installation

First, verify the CLI is installed and can reach the Affinity API. See CLI: Verify Installation.

# Check CLI is installed

xaffinity --version

Check API connectivity (set your API key - same one entered in Claude Desktop)

AFFINITY_API_KEY="your-key-here" xaffinity whoami --json

If whoami hangs, check network connectivity (firewall, proxy, VPN).

Step 2: MCP Server

Once the CLI works, test the MCP server end-to-end.

First, locate your MCP server directory:

# MCPB installation (macOS)

cd ~/Library/Application\ Support/Claude/Claude\ Extensions/local.mcpb.yaniv-golan.xaffinity-mcp/server

Or find it automatically

cd "$(find ~ -name 'xaffinity-mcp.sh' -type f 2>/dev/null | head -1 | xargs dirname)"

Other platforms/installations

For MCPB installations: If Step 1 passes, your setup is complete. The MCP server shells out to CLI, so if CLI works with your API key, the MCP server will too. Restart Claude Desktop and test the tools there.

For manual installations: You can also test the MCP layer directly:

AFFINITY_API_KEY="your-key-here" \

mcp-bash run-tool execute-read-command \ --args '{"command":"whoami"}'

Expected: JSON response with your user information.

If Step 1 works but Step 2 fails, the issue is MCP-specific. Run diagnostics (these need the full mcp-bash install, not just the vendored runtime — see step 4 of manual installation):

./xaffinity-mcp.sh doctor

./xaffinity-mcp.sh validate

Common Issues

For detailed debugging, see docs/DEBUGGING.md.

Usage

With Claude Code

The server is automatically available through the Claude plugin at .claude-plugin/mcp.json.

With Other MCP Clients

Add to your MCP client configuration:

{

"mcpServers": { "xaffinity": { "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh" } } }

Tools

CLI Gateway (Primary Interface)

The CLI Gateway provides full access to the xaffinity CLI with minimal token overhead:

Query Tool

For complex data analysis (filtering, grouping, aggregations), use the query tool instead of individual CLI commands. See the Query Language Reference for full documentation.

Utility Tools

CLI Gateway Usage

1. Discover the right command:

   {"query": "add person to list", "category": "write"}

Returns compact text format:

   # cmd|cat|params (s=str i=int b=bool f=flag !=req *=multi)

list entry add|w|LIST:s! --person-id:i --company-id:i

1. Execute the command:

   {"command": "list entry add", "argv": ["Pipeline", "--person-id", "123"]}

Output Formats

Control the format of command results for optimal token efficiency:

{"command": "person ls", "format": "markdown"}

Recommendations:

• Use markdown when you need to analyze or summarize data (LLMs read tables well)
• Use toon for large exports to minimize tokens (30-60% smaller than JSON)
• Use json when you need full structure with pagination/metadata

Destructive Commands

Commands that cannot be undone (delete, merge) need the user's confirmation:

• In clients that support confirmation dialogs (MCP elicitation), the server asks you directly.
• Claude Desktop extensions get no dialog. The tool refuses the first call and tells Claude to ask you in the conversation; Claude retries with confirm: true only after you agree:

{"command": "person delete", "argv": ["456"], "confirm": true}

The tool appends --yes for the CLI. Since MCP 1.27.0 confirm: true counts only after the server refused that exact command (or showed its dialog) in the last 15 minutes, once: if Claude sets it on its first call, the call is refused and Claude is told to ask you. The server can't see the conversation, so it can't tell whether you really agreed: **keep Claude Desktop's tool-approval prompt on for execute-write-command and don't choose "always allow