Breakcold .NET SDK & CLI

A complete .NET solution for interacting with the Breakcold API v3, including a library SDK and a CLI tool with MCP (Model Context Protocol) server support.

Created with ❤️ by the team from Ivy Framework.

📦 What's Included

• Ivy.Breakcold - .NET 9.0 library for Breakcold API v3
• Ivy.Breakcold.Console - Command-line tool and MCP server for Claude Desktop & Claude Code

🚀 Installation

CLI Tool (Ivy.Breakcold.Console)

Install the CLI tool globally:

dotnet tool install --global Ivy.Breakcold.Console

Verify installation:

breakcold --help

Library (Ivy.Breakcold)

Install the library via NuGet:

dotnet add package Ivy.Breakcold

🔑 API Key Configuration

The CLI tool supports multiple methods for providing your API key (checked in priority order):

Option 1: User Secrets (Recommended for Development)

dotnet user-secrets set "Breakcold:ApiKey" "your-api-key-here" --id ivy-breakcold-console

Option 2: Environment Variable

Linux/macOS:

export BREAKCOLD_API_KEY="your-api-key-here"

Windows (PowerShell):

$env:BREAKCOLD_API_KEY="your-api-key-here"

Windows (Command Prompt):

set BREAKCOLD_API_KEY=your-api-key-here

🤖 MCP Server Integration

The Breakcold CLI can function as an MCP (Model Context Protocol) server, allowing Claude Desktop and Claude Code to interact with your Breakcold CRM directly.

Available MCP Tools

When running as an MCP server, the following 23 tools are available:

User & Workspace:

• get_me - Get current user details
• list_workspaces - List all workspaces
• get_workspace_members - Get members of a workspace

Lead Management:

• list_leads - List all leads from Breakcold
• get_lead - Get a lead by ID
• create_lead - Create a new lead
• update_lead - Update a lead
• delete_lead - Delete a lead by ID
• search_leads - Search for leads by query

Tag Management:

• list_tags - List all tags
• get_tag - Get a tag by ID
• create_tag - Create a new tag
• update_tag - Update a tag
• delete_tag - Delete a tag by ID

List Management:

• list_lists - List all lists
• create_list - Create a new list
• add_leads_to_list - Add leads to a list

Note Management:

• list_notes - List all notes
• get_note - Get a note by ID
• create_note - Create a new note

Reminder Management:

• list_reminders - List all reminders
• create_reminder - Create a new reminder

Attributes:

• list_attributes - List all custom attributes

Claude Desktop Setup

1. Find your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Breakcold MCP server configuration:

{
  "mcpServers": {
    "breakcold": {
      "command": "breakcold",
      "args": ["--mcp"],
      "env": {
        "BREAKCOLD_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Restart Claude Desktop

4. You should now see the Breakcold tools available in Claude Desktop. Try asking: "List my Breakcold leads"

Claude Code Setup

1. Find your Claude Code MCP settings file:

   • macOS/Linux: ~/.config/claude-code/mcp_settings.json
   • Windows: %APPDATA%\claude-code\mcp_settings.json

2. Add the Breakcold MCP server configuration:

{
  "mcpServers": {
    "breakcold": {
      "command": "breakcold",
      "args": ["--mcp"],
      "env": {
        "BREAKCOLD_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Restart Claude Code or reload the MCP servers

4. The Breakcold tools will be available in your coding sessions. Example prompts:

   • "Search for leads with email containing 'example.com'"
   • "Create a new lead for Jane Smith with email jane@company.com"
   • "Show me all my Breakcold workspaces"

Manual MCP Server Testing

You can test the MCP server manually:

# Start the MCP server (listens on STDIN/STDOUT)
breakcold --mcp

# Send an initialize request (in a separate terminal or via pipe)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | breakcold --mcp

💻 CLI Usage

User Commands

# Get current user details
breakcold me

Workspace Commands

# List all workspaces
breakcold workspace list

# Get workspace members
breakcold workspace members <WORKSPACE_ID>

Lead Commands (9 commands)

# List all leads
breakcold lead list

# Get a specific lead by ID
breakcold lead get <LEAD_ID>

# Create a new lead
breakcold lead create --first-name John --last-name Doe --email john@example.com

# Update a lead
breakcold lead update <LEAD_ID> --email newemail@example.com --phone "+1234567890"

# Delete a lead
breakcold lead delete <LEAD_ID>

# Delete multiple leads
breakcold lead delete-many <ID1,ID2,ID3>

# Search for leads
breakcold lead search "john"

# Connect lead to company
breakcold lead connect-company <LEAD_ID> <COMPANY_ID>

# Disconnect lead from company
breakcold lead disconnect-company <LEAD_ID>

Tag Commands (5 commands)

# List all tags
breakcold tag list

# Get a tag by ID
breakcold tag get <TAG_ID>

# Create a new tag
breakcold tag create "Important" --color "#FF0000"

# Update a tag
breakcold tag update <TAG_ID> --name "High Priority" --color "#00FF00"

# Delete a tag
breakcold tag delete <TAG_ID>

List Commands (8 commands)

# List all lists
breakcold list all

# Create a new list
breakcold list create "Prospects" --emoji "🎯" --description "Potential customers"

# Update a list
breakcold list update <LIST_ID> --name "Hot Prospects"

# Delete a list
breakcold list delete <LIST_ID>

# Duplicate a list
breakcold list duplicate <LIST_ID>

# Add leads to a list
breakcold list add-leads <LIST_ID> <LEAD_ID1,LEAD_ID2>

# Move leads to a list
breakcold list move-leads <LIST_ID> <LEAD_ID1,LEAD_ID2>

# Remove leads from a list
breakcold list remove-leads <LIST_ID> <LEAD_ID1,LEAD_ID2>

Note Commands (5 commands)

# List all notes
breakcold note list

# Get a note by ID
breakcold note get <NOTE_ID>

# Create a new note
breakcold note create "Follow up tomorrow" --lead-id <LEAD_ID>

# Update a note
breakcold note update <NOTE_ID> --content "Updated note content"

# Delete a note
breakcold note delete <NOTE_ID>

Reminder Commands (4 commands)

# List all reminders
breakcold reminder list

# Create a new reminder
breakcold reminder create "Call John" --due-date "2024-12-31T10:00:00" --lead-id <LEAD_ID>

# Update a reminder
breakcold reminder update <REMINDER_ID> --title "Call John ASAP" --completed true

# Delete a reminder
breakcold reminder delete <REMINDER_ID>

Status Commands (4 commands)

# Create a new status
breakcold status create "Qualified" --color "#00FF00"

# Update a status
breakcold status update <STATUS_ID> --name "Hot Lead"

# Update many statuses
breakcold status update-many '[{"id":"123","name":"Updated"}]'

# Delete a status
breakcold status delete <STATUS_ID>

Attribute Commands (4 commands)

# List all attributes
breakcold attribute list

# Create a new attribute
breakcold attribute create "Industry" --type "text"

# Update an attribute
breakcold attribute update <ATTRIBUTE_ID> --name "Company Size"

# Delete an attribute
breakcold attribute delete <ATTRIBUTE_ID>

📚 API Library Usage

Basic Usage

using Ivy.Breakcold;

var client = new BreakcoldClient(new BreakcoldClientOptions
{
    ApiKey = "your-api-key-here"
});

// Get current user
var user = await client.Users.GetMeAsync();
Console.WriteLine($"Logged in as: {user.Email}");

// List all leads
var leads = await client.Leads.ListAsync();

Dependency Injection

using Ivy.Breakcold;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();

services.AddBreakcoldClient(options =>
{
    options.ApiKey = "your-api-key-here";
    options.BaseUrl = "https://api.breakcold.com/rest/"; // Optional (default)
    options.Timeout = TimeSpan.FromSeconds(30); // Optional (default)
});

var serviceProvider = services.BuildServiceProvider();
var client = serviceProvider.GetRequiredService<BreakcoldClient>();

API Coverage

100% coverage of Breakcold API v3 (45 endpoints across 9 services)

User

• GetMeAsync() - Get authenticated user details

Workspaces

• GetWorkspacesAsync() - Get user workspaces
• GetMembersAsync(workspaceId) - Get members of a workspace

Leads

• CreateAsync(lead) - Create a new lead
• GetByIdAsync(leadId) - Get a lead by ID
• UpdateAsync(leadId, lead) - Update a lead
• DeleteAsync(leadId) - Delete a lead
• DeleteManyAsync(leadIds) - Delete many leads
• ListAsync(filters) - List leads with pagination and filters
• SearchAsync(query) - Search leads
• ConnectToCompanyAsync(leadId, companyId) - Connect a lead to a company
• DisconnectFromCompanyAsync(leadId) - Disconnect a lead from a company

Tags

• ListAsync() - List all tags
• CreateAsync(tag) - Create a new tag
• GetByIdAsync(tagId) - Get a tag by ID
• UpdateAsync(tagId, tag) - Update a tag
• DeleteAsync(tagId) - Delete a tag

Lists

• GetAllAsync() - Get all lists
• CreateAsync(list) - Create a new list
• UpdateAsync(listId, list) - Update a list
• DeleteAsync(listId) - Delete a list
• DuplicateAsync(listId) - Duplicate a list
• AddLeadsAsync(listId, leadIds) - Add many leads to a list
• MoveLeadsAsync(listId, leadIds) - Move many leads to a list
• RemoveLeadsAsync(listId, leadIds) - Remove many leads from a list

Notes

• ListAsync(filters) - List notes with filters
• CreateAsync(note) - Create a new note
• GetByIdAsync(noteId) - Get a note by ID
• UpdateAsync(noteId, note) - Update a note
• DeleteAsync(noteId) - Delete a note

Reminders

• ListAsync(filters) - List reminders with filters and pagination
• CreateAsync(reminder) - Create a new reminder
• UpdateAsync(reminderId, reminder) - Update a reminder
• DeleteAsync(reminderId) - Delete a reminder

Statuses

• CreateAsync(status) - Create a new status
• UpdateAsync(statusId, status) - Update a status
• UpdateManyAsync(statuses) - Update many statuses
• DeleteAsync(statusId) - Delete a status

Attributes

• ListAsync() - List all attributes
• CreateAsync(attribute) - Create a new attribute
• UpdateAsync(attributeId, attribute) - Update an attribute
• DeleteAsync(attributeId) - Delete an attribute

Examples

Creating a Lead

var lead = new Lead
{
    FirstName = "John",
    LastName = "Doe",
    Email = "john.doe@example.com",
    Phone = "+1234567890"
};

var createdLead = await client.Leads.CreateAsync(lead);
Console.WriteLine($"Created lead: {createdLead.Id}");

Searching Leads

var results = await client.Leads.SearchAsync("john");
foreach (var lead in results)
{
    Console.WriteLine($"{lead.FirstName} {lead.LastName} - {lead.Email}");
}

Managing Tags

// Create a tag
var tag = new Tag
{
    Name = "Important",
    Color = "#FF0000"
};

var createdTag = await client.Tags.CreateAsync(tag);

// List all tags
var tags = await client.Tags.ListAsync();

Working with Lists

// Create a list
var list = new LeadList
{
    Name = "Prospects",
    Description = "Potential customers",
    Emoji = "🎯"
};

var createdList = await client.Lists.CreateAsync(list);

// Add leads to the list
var leadIds = new List<string> { "lead-id-1", "lead-id-2" };
await client.Lists.AddLeadsAsync(createdList.Id, leadIds);

Configuration

BreakcoldClientOptions

• ApiKey (required) - Your Breakcold API key (get it from https://app.breakcold.com/settings/integrations)
• BaseUrl (optional) - API base URL (default: https://api.breakcold.com/rest/)
• Timeout (optional) - HTTP request timeout (default: 30 seconds)

🛠️ Development

Building from Source

# Clone the repository
git clone https://github.com/ivy-interactive/breakcold-cli.git
cd breakcold-cli

# Build the library
dotnet build Ivy.Breakcold

# Build the CLI tool
dotnet build Ivy.Breakcold.Console

# Run the CLI locally
dotnet run --project Ivy.Breakcold.Console -- me

Running Tests

# Build in Release mode
dotnet build --configuration Release

# Pack the library
dotnet pack Ivy.Breakcold --configuration Release --output ./packages

# Pack the CLI tool
dotnet pack Ivy.Breakcold.Console --configuration Release --output ./packages

# Install locally for testing
dotnet tool install --global Ivy.Breakcold.Console --add-source ./packages --version 1.0.0

# Test the installed tool
breakcold me

🔧 Troubleshooting

CLI Tool Not Found

If breakcold command is not found after installation:

# Check if the tool is installed
dotnet tool list --global

# Ensure .NET tools are in your PATH
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):
export PATH="$PATH:$HOME/.dotnet/tools"

API Authentication Errors

If you get 401/403 errors:

1. Verify your API key is correct
2. Check the API key is properly set (try with explicit env var)
3. Ensure the API key has the necessary permissions

# Test with explicit environment variable
BREAKCOLD_API_KEY="your-api-key" breakcold me

MCP Server Issues

If the MCP server doesn't appear in Claude Desktop/Code:

1. Verify the tool is installed globally: breakcold --version
2. Check the configuration file syntax is valid JSON
3. Ensure the API key is correctly set in the env section
4. Restart Claude Desktop/Code after configuration changes
5. Check Claude's developer logs for connection errors

📖 Documentation

• Breakcold API Documentation
• Deployment Guide - Instructions for publishing to NuGet

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

🙋 Support

For issues or questions:

• GitHub Issues: [repository-url]/issues
• Breakcold API Docs: https://developer.breakcold.com/v3/api-reference/