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 v2. This server enables LLMs to interact with Affinity data including companies, persons, lists, and more.

Features

9 Tools for comprehensive Affinity access:
- affinity_whoami - Verify authentication and permissions
- affinity_list_companies - List companies with optional field data
- affinity_get_company - Get company details by ID
- affinity_list_persons - List persons with optional field data
- affinity_get_person - Get person details by ID
- affinity_list_lists - Discover available lists
- affinity_get_list_entries - Get entries from any list
- affinity_list_opportunities - List opportunities
- affinity_get_opportunity - Get opportunity details by ID
Pagination - Cursor-based pagination for large datasets
Rate Limiting - Automatic handling of API rate limits with retry
Request Timeout - 30-second timeout prevents hung requests
Error Handling - Clear, actionable error messages

Installation

# Clone the repository
git clone <repo-url>
cd affinity-mcp

# Install dependencies
npm install

# Build
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

Log into Affinity web app
Go to Settings
Generate an API key (requires "Generate an API key" permission)
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": "node",
      "args": ["/path/to/affinity-mcp/dist/index.js"],
      "env": {
        "AFFINITY_API_KEY": "your_api_key_here"
      }
    }
  }
}

With Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "affinity": {
      "command": "node",
      "args": ["/path/to/affinity-mcp/dist/index.js"],
      "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_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_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_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_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"

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