JSPM

@alludium/affinity-mcp-server

1.0.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 110
  • Score
    100M100P100Q80949F
  • License MIT

MCP server for Affinity CRM API

Package Exports

  • @alludium/affinity-mcp-server
  • @alludium/affinity-mcp-server/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@alludium/affinity-mcp-server) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Affinity MCP Server

An MCP (Model Context Protocol) server for the Affinity CRM API. This server enables LLMs to interact with Affinity data including companies, persons, lists, opportunities, notes, and pipeline management.

Features

  • 23 Tools for comprehensive Affinity access
  • Dual API Support - Uses both V1 and V2 Affinity APIs for full functionality
  • Pagination - Cursor-based pagination for large datasets
  • Response Formats - JSON and Markdown output options
  • Rate Limiting - Automatic handling of API rate limits with retry
  • Request Timeout - 30-second timeout prevents hung requests
  • Error Handling - Clear, actionable error messages
  • Character Limits - Automatic truncation to prevent oversized responses

Tools Overview

Authentication

Tool Description
affinity_whoami Verify authentication and get current user info, permissions

Companies (4 tools)

Tool Description
affinity_list_companies List companies with optional field data (V2)
affinity_get_company Get company details by ID (V2)
affinity_search_companies Search companies by name or domain (V1)
affinity_create_company Create a new company (V1)

Persons (4 tools)

Tool Description
affinity_list_persons List persons with optional field data (V2)
affinity_get_person Get person details by ID (V2)
affinity_search_persons Search persons by email, name (V1)
affinity_create_person Create a new person (V1)

Lists & Pipelines (6 tools)

Tool Description
affinity_list_lists Discover available lists
affinity_get_list Get single list metadata
affinity_get_list_entries Get entries from any list
affinity_get_list_fields Get field definitions for a list
affinity_get_swimlanes Get pipeline stages (Status field values)
affinity_get_companies_in_swimlane Get companies at a specific pipeline stage

Opportunities (2 tools)

Tool Description
affinity_list_opportunities List opportunities
affinity_get_opportunity Get opportunity details by ID

Notes (4 tools)

Tool Description
affinity_list_company_notes List notes for a company (V2 BETA)
affinity_list_person_notes List notes for a person (V2 BETA)
affinity_list_opportunity_notes List notes for an opportunity (V2 BETA)
affinity_add_note Create a note attached to entities (V1)

Enhanced Details (2 tools)

Tool Description
affinity_get_company_lists Get lists containing a company
affinity_get_company_list_entries Get list entry data for a company

Installation

No installation required when using npx (see Usage below).

Optional: Global Install

npm install -g @alludium/affinity-mcp-server

Optional: From Source

git clone https://github.com/alludium/affinity-mcp-server.git
cd affinity-mcp-server
npm install
npm run build

Configuration

Set your Affinity API key as an environment variable:

export AFFINITY_API_KEY=your_api_key_here

When using with Claude Desktop or Claude Code, set the key in the MCP server configuration's env block (see Usage section below).

Getting an API Key

  1. Log into Affinity web app
  2. Go to Settings
  3. Generate an API key (requires "Generate an API key" permission)
  4. Copy the key - it won't be shown again!

Usage

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "affinity": {
      "command": "npx",
      "args": ["-y", "@alludium/affinity-mcp-server"],
      "env": {
        "AFFINITY_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "affinity": {
      "command": "npx",
      "args": ["-y", "@alludium/affinity-mcp-server"],
      "env": {
        "AFFINITY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development Mode

# Run with tsx for development
AFFINITY_API_KEY=your_key npm run dev

Tools Reference

affinity_whoami

Verify authentication and get current user info.

No parameters required

Returns: User info, organization details, API key permissions

affinity_list_companies

List companies with optional field data.

Parameter Type Description
ids number[] Filter by specific company IDs
fieldTypes string[] Field types: "enriched", "global"
fieldIds string[] Specific field IDs to return
limit number Results per page (max 100)
cursor string Pagination cursor
responseFormat string "json" or "markdown"

affinity_get_company

Get detailed info about a single company.

Parameter Type Required Description
companyId string Yes Company ID (numeric)
fieldTypes string[] No Field types: "enriched", "global"
fieldIds string[] No Specific field IDs to return
responseFormat string No "json" or "markdown"

affinity_search_companies

Search for companies by name or domain (V1 API).

Parameter Type Description
term string Search term: company name or domain
withInteractionDates boolean Include first/last interaction timestamps
withInteractionPersons boolean Include persons involved in interactions
withOpportunities boolean Include opportunity IDs
pageSize number Items per page (max 500)
pageToken string Pagination token
responseFormat string "json" or "markdown"

affinity_create_company

Create a new company/organization (V1 API).

Parameter Type Required Description
name string Yes Company name
domain string No Primary domain
domains string[] No Additional domains
responseFormat string No "json" or "markdown"

affinity_list_persons

List persons/contacts with optional field data.

Parameter Type Description
ids number[] Filter by specific person IDs
fieldTypes string[] Field types: "enriched", "global", "relationship-intelligence"
fieldIds string[] Specific field IDs to return
limit number Results per page (max 100)
cursor string Pagination cursor
responseFormat string "json" or "markdown"

affinity_get_person

Get detailed info about a single person.

Parameter Type Required Description
personId string Yes Person ID (numeric)
fieldTypes string[] No Field types to include
fieldIds string[] No Specific field IDs to return
responseFormat string No "json" or "markdown"

affinity_search_persons

Search for persons by email, first name, or last name (V1 API).

Parameter Type Description
term string Search term: email, first name, or last name
withInteractionDates boolean Include first/last interaction timestamps
withInteractionPersons boolean Include persons involved in interactions
withOpportunities boolean Include opportunity IDs
withCurrentOrganizations boolean Include current organization IDs
pageSize number Items per page (max 500)
pageToken string Pagination token
responseFormat string "json" or "markdown"

affinity_create_person

Create a new person (V1 API).

Parameter Type Required Description
firstName string Yes First name
lastName string Yes Last name
emails string[] No Email addresses (first becomes primary)
organizationIds number[] No Organization IDs to associate
responseFormat string No "json" or "markdown"

affinity_list_lists

Get all lists in the workspace.

Parameter Type Description
limit number Results per page (max 100)
cursor string Pagination cursor
responseFormat string "json" or "markdown"

Returns: All lists with their IDs, names, types, and ownership info

affinity_get_list

Get metadata for a single list.

Parameter Type Required Description
listId string Yes List ID (numeric)
responseFormat string No "json" or "markdown"

affinity_get_list_entries

Get entries from a specific list.

Parameter Type Required Description
listId string Yes List ID (numeric)
fieldTypes string[] No Field types: "enriched", "global", "list"
fieldIds string[] No Specific field IDs to return
limit number No Results per page (max 100)
cursor string No Pagination cursor
responseFormat string No "json" or "markdown"

affinity_get_list_fields

Get field definitions for a list.

Parameter Type Required Description
listId string Yes List ID (numeric)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

affinity_get_swimlanes

Get pipeline stages (swimlanes) for a list.

Parameter Type Required Description
listId string Yes List ID (numeric)
responseFormat string No "json" or "markdown"

Returns: Status field ID and all swimlane stages with IDs, names, ranks, colors

affinity_get_companies_in_swimlane

Get companies at a specific pipeline stage.

Parameter Type Required Description
listId string Yes List ID (numeric)
swimlaneId string Yes Swimlane/stage ID (from affinity_get_swimlanes)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

affinity_list_opportunities

List opportunities from Affinity.

Parameter Type Description
ids number[] Filter by specific opportunity IDs
limit number Results per page (max 100)
cursor string Pagination cursor
responseFormat string "json" or "markdown"

affinity_get_opportunity

Get details about a single opportunity.

Parameter Type Required Description
opportunityId string Yes Opportunity ID (numeric)
responseFormat string No "json" or "markdown"

affinity_list_company_notes

List notes attached to a company (V2 BETA).

Parameter Type Required Description
companyId string Yes Company ID (numeric)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

affinity_list_person_notes

List notes attached to a person (V2 BETA).

Parameter Type Required Description
personId string Yes Person ID (numeric)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

affinity_list_opportunity_notes

List notes attached to an opportunity (V2 BETA).

Parameter Type Required Description
opportunityId string Yes Opportunity ID (numeric)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

affinity_add_note

Create a note attached to companies, persons, or opportunities (V1 API).

Note: Notes are add-only. Edit and delete are not supported.

Parameter Type Required Description
content string Yes Note content (plain text or HTML)
companyIds number[] No* Company IDs to attach note to
personIds number[] No* Person IDs to attach note to
opportunityIds number[] No* Opportunity IDs to attach note to
contentType string No "text" (default) or "html"
responseFormat string No "json" or "markdown"

*At least one of companyIds, personIds, or opportunityIds is required.

affinity_get_company_lists

Get lists containing a specific company.

Parameter Type Required Description
companyId string Yes Company ID (numeric)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

affinity_get_company_list_entries

Get full list entry data for a company across all lists.

Parameter Type Required Description
companyId string Yes Company ID (numeric)
cursor string No Pagination cursor
limit number No Items per page (max 100)
responseFormat string No "json" or "markdown"

Rate Limits

  • 900 requests per minute per user
  • Automatic retry with backoff on 429 responses
  • Rate limit headers tracked for monitoring

Error Handling

The server returns clear, actionable error messages:

  • 401: Check your API key
  • 403: Use affinity_whoami to check permissions
  • 404: Resource not found
  • 429: Rate limited, wait and retry

Development

# Type check
npm run typecheck

# Build
npm run build

# Run in dev mode
npm run dev

License

MIT