affinity-mcp 0.1.1

Affinity MCP server

affinity-mcp: An Affinity MCP Server

A Model Context Protocol (MCP) server to interact with the Affinity APIs.

• Version 2
• Version 1

Note: When this MCP server makes requests to the Affinity API, it includes a User-Agent header that identifies the request as coming from the Affinity MCP Server. This helps the Affinity team understand API usage patterns and provide better support for MCP-specific issues.

Features

Persons

• Search Persons: Search for persons by name or email, with optional filtering by interaction dates (first/last email, meetings)
• Get Person Info: Retrieve detailed information about a person including current organization, job title, and more.
• Get Person List Entries: View which lists a person appears on

Companies

• Search Companies: Search for companies by name or domain, with optional filtering by interaction history
• Get Company Info: Retrieve detailed information about a company including location, description, and more.
• Get Company List Entries: View which lists a company appears on

Opportunities

• Search Opportunities: Search for opportunities by keyword or list all opportunities

Notes

• Create Note: Create an HTML note and attach it to persons, companies, or opportunities
• Get Notes: Find notes with filtering by ID, creator, or creation date
• Get Notes for Entity: Retrieve all notes attached to a specific person, company, or opportunity
• Get Entities Attached to Note: Find all persons, companies, or opportunities linked to a specific note

Lists

• Get Lists: View all lists in your organization that you have access to
• Get List Info: Retrieve metadata about a specific list
• Get List Entries: Retrieve list entries from a specific list
• Get Single List Entry: Retrieve metadata about a single list entry from a specific list

Meetings

• Get Meetings: Retrieve past and future meetings with filtering by meeting ID, start time, creation time, or update time
• Get Meetings for Entity: Retrieve past and future meetings for a specific company, person, or opportunity, with filtering by internal person and logging type

Fields

• Get Entity Fields: View metadata about available fields for companies or persons
• Get List Fields: View metadata about available fields for a specific list

Auth

• Get Current User: Get information about the current user and organization

Prerequisites

1. Setup API Key

Follow the steps in this article to obtain your Affinity API key.

⚠️ Never store your API key in .env files or commit it to version control. Always store it in an environment variable as shown in the configuration examples below.

2. Install UV

Install UV Python package manager (recommended over pip for simpler dependency management)

MCP Client Configuration

• Claude
  • Claude CLI
  • Claude Desktop
• ChatGPT
• Gemini
  • Gemini CLI
• GitHub Copilot
  • Copilot VSCode
  • Copilot CLI
• Other Clients

Claude Setup

Claude CLI

1. Add server

   Run the following command with your API key:

   claude mcp add affinity-mcp \
       --scope user \
       --transport stdio \
       --env AFFINITY_API_KEY=your_api_key_here \
       -- uvx affinity-mcp
   

2. Verify MCP server configuration

   1. Run command: claude mcp list
   2. Ensure that the following server is connected: affinity-mcp: uvx affinity-mcp - ✓ Connected

Claude Desktop

Reference: Connect Local MCP Servers to Claude Desktop

1. Go to File → Settings → Developer → Edit Config and open claude_desktop_config.json.
2. Run which uvx in your terminal and copy the full path it returns.
3. Add the following to the config, replacing the command with the path from the previous step and the API key with your own:

   {
     "mcpServers": {
       "affinity-mcp": {
         "command": "your-uvx-path-here",
         "args": ["affinity-mcp"],
         "env": {
           "AFFINITY_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

4. Restart Claude Desktop to apply the changes.

ChatGPT Setup

Note: We must use Ngrok to expose the local Affinity MCP server to be used by ChatGPT.

1. Ensure ChatGPT Developer Mode is enabled

   1. Go to ChatGPT > Connect More > Advanced Settings
   2. Enable Developer Mode

2. Run the Affinity MCP server locally

   1. Run the MCP server using the MCP inspector command:

   npx @modelcontextprotocol/inspector uvx affinity-mcp -e AFFINITY_API_KEY=your_api_key_here
   

   2. Note the port it's running on and the auth token.

3. Expose the server with ngrok

   1. Run ngrok http with the port number of your server (e.g., if port is 8000):

   ngrok http 8000
   

   2. ngrok should return the public url you can use to connect to on ChatGPT.

4. Connect through ChatGPT

   1. Next to Enabled apps & connectors click the Create button to create a new connector.
   2. Use the following fields:
   • Name: affinity-mcp
   • MCP Server URL: <Name of public url ngrok provided>

Gemini Setup

Reference: Gemini CLI MCP Configuration

Gemini CLI

1. Open settings.json

   1. Go to ~/.gemini
   2. Open settings.json

2. Add server to config file

   Add the server configurations to the config file:

   {
     //...file contains other config objects
     "mcpServers": {
       "affinity-mcp": {
         "command": "uvx",
         "args": ["affinity-mcp"],
         "env": {
           "AFFINITY_API_KEY": "your_api_key_here"
         },
         "trust": false
       }
     }
   }
   

3. Verify server is connected

   1. Run gemini mcp list or run gemini → /mcp
   2. You should see your server connected:

   Configured MCP servers:
   
   ✓ affinity-mcp: uvx affinity-mcp (stdio) - Connected
   

GitHub Copilot Setup

Copilot VSCode

1. Add server through VSCode

   1. Open the command palette by pressing Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux). You'll see a search bar appear at the top of VSCode.
   2. Type >MCP: Add Server in the search bar and select it from the dropdown.
   3. Select Command (stdio) when prompted
   4. Enter uvx affinity-mcp as the command
   5. Enter affinity-mcp as the Server ID
   6. When prompted for a configuration, choose Global if you want the MCP server to be available in all workspaces, or choose a specific workspace.

2. Add API Key

   1. You should now be able to see a new .vscode/mcp.json file
   2. Open it to verify the configuration.
   3. Underneath args, add your API key:

   "env": {
       "AFFINITY_API_KEY": "your_api_key_here"
   }
   

   Your configuration should look like this:

   {
     "servers": {
       "affinity-mcp": {
         "type": "stdio",
         "command": "uvx",
         "args": [
           "affinity-mcp"
         ],
         "env": {
           "AFFINITY_API_KEY": "your_api_key_here"
         }
       }
     },
     "inputs": []
   }
   

3. On the Copilot panel in VSCode, try asking it "What are the available tools?" and you should be able to see the available tools for Affinity MCP.

Copilot CLI

1. Run Copilot CLI

2. Add server using /mcp

   1. Run /mcp add
   2. Add the server information:

   Server Name: affinity-mcp
   Server Type: STDIO
   Command: uvx affinity-mcp
   Environment Variables: {"AFFINITY_API_KEY": "your_api_key_here"}
   Tools: *
   

   3. Save and add server.

3. Verify configurations

   1. Run /mcp show and you should see the server is connected.
   2. Open ~/.copilot/mcp_config.json to verify.

   {
     "mcpServers": {
       "affinity-mcp": {
         "tools": [
           "*"
         ],
         "type": "stdio",
         "command": "uvx",
         "args": [
           "affinity-mcp"
         ],
         "env": {
           "AFFINITY_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

Other Clients

See MCP Clients for more options.

Troubleshooting

View Server Logs

If the server isn't working as expected, you can view the logs to debug issues.

macOS (Claude Desktop): Open a terminal and run:

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

Windows (Claude Desktop): Logs are typically located in %APPDATA%\Roaming\Claude\logs.

Common Issues

1. "Authentication failed" or 401 Errors

• Cause: The AFFINITY_API_KEY environment variable is missing or invalid.
• Fix: Double-check your API key. Ensure there are no extra spaces or quotes around the key.

2. "Connection refused" or Timeout

• Cause: The server cannot reach api.affinity.co.
• Fix:
  • Check your internet connection.
  • If you are on a corporate VPN, ensure it allows traffic to Affinity's API.

3. Changes to API key not taking effect

• Cause: Claude Desktop loads environment variables when it starts.
• Fix: You must fully quit and restart Claude Desktop.

4. "Tool not found"

• Cause: The MCP server might have crashed or failed to start.
• Fix: Check the logs (see above) for startup errors.

Security

The MCP server acts as a wrapper around the Affinity APIs and does not create a new data access mechanism. The trust boundary and access controls remain at the API layer.

Vulnerability Reporting

If you discover a security vulnerability, please refer to our Security Policy for more information about the disclosure procedure.

Software Bill of Materials (SBOM)

A Software Bill of Materials (SBOM) is automatically generated and included with each release for compliance and security auditing purposes. The SBOM provides a complete inventory of all dependencies and their versions in CycloneDX JSON format.

Access the SBOM:

Option 1: Download from PyPI website

1. Visit the PyPI package page
2. Navigate to the Download files tab
3. Download the .tar.gz source distribution file
4. Extract and view the SBOM:

   tar -xzf affinity_mcp-{version}.tar.gz
   cat affinity_mcp-{version}/src/affinity_mcp/affinity-mcp-{version}-sbom.json
   

Option 2: Use pip to download

pip download affinity-mcp --no-deps --no-binary :all:
tar -xzf affinity_mcp-*.tar.gz
cat affinity_mcp-*/src/affinity_mcp/affinity-mcp-*-sbom.json

The SBOM can be used with security scanning tools to audit dependencies and identify potential vulnerabilities.

Terms of Use

This MCP server is governed by Affinity's Terms of Use. By using this server, you agree to comply with these terms.