Can I use Copper CRM as a CLI?

Yes. KosmoKrator exposes a Copper CRM CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Copper CRM through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Copper CRM tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Copper CRM credentials stored?

Copper CRM credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Copper CRM MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Copper CRM Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Copper CRM KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.copper.*. Use lua_read_doc("integrations.copper") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Copper CRM workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.copper.list_contacts({page_size = 1, sort_by = "example_sort_by"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("copper"))' --json
kosmo integrations:lua --eval 'print(docs.read("copper.list_contacts"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local copper = app.integrations.copper
local result = copper.list_contacts({page_size = 1, sort_by = "example_sort_by"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.copper, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.copper.default.* or app.integrations.copper.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Copper CRM, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Copper CRM Lua API Reference

Namespace: copper

Copper calls contact records “People” in the official API. This package keeps the existing contact tool names for agent compatibility while routing them to Copper /people endpoints.

Authentication

Copper requires:

api_key
email
optional url, defaulting to https://api.copper.com/developer_api/v1

People / Contacts

local people = app.integrations.copper.list_contacts({
  page_size = 25,
  page_number = 1,
  sort_by = "name",
})

local person = app.integrations.copper.get_contact({ id = 123 })

local by_email = app.integrations.copper.get_contact_by_email({
  email = "ada@example.test",
})

local created = app.integrations.copper.create_contact({
  name = "Ada Example",
  email = "ada@example.test",
})

local updated = app.integrations.copper.update_contact({
  id = 123,
  name = "Ada Lovelace",
})

app.integrations.copper.delete_contact({ id = 123 })

Companies

local companies = app.integrations.copper.list_companies({
  page_size = 25,
  sort_by = "name",
})

local company = app.integrations.copper.get_company({ id = 456 })

local created = app.integrations.copper.create_company({
  name = "Example Corp",
})

app.integrations.copper.update_company({
  id = 456,
  details = "Enterprise account",
})

app.integrations.copper.delete_company({ id = 456 })

Opportunities

local opportunities = app.integrations.copper.list_opportunities({
  page_size = 25,
  pipeline_ids = { 10 },
})

local opportunity = app.integrations.copper.get_opportunity({ id = 789 })

local created = app.integrations.copper.create_opportunity({
  name = "Example renewal",
  pipeline_id = 10,
})

app.integrations.copper.update_opportunity({
  id = 789,
  monetary_value = 250000,
  win_probability = 70,
})

app.integrations.copper.delete_opportunity({ id = 789 })

Leads

local leads = app.integrations.copper.list_leads({
  page_size = 25,
  email = "buyer@example.test",
})

local lead = app.integrations.copper.get_lead({ id = 111 })

local created = app.integrations.copper.create_lead({
  name = "Buyer Example",
  company_name = "Example Corp",
  status_id = 222,
})

app.integrations.copper.update_lead({
  id = 111,
  details = "Qualified inbound lead",
})

app.integrations.copper.delete_lead({ id = 111 })

Projects And Tasks

local projects = app.integrations.copper.list_projects({
  page_size = 25,
})

local project = app.integrations.copper.create_project({
  name = "Implementation",
  company_id = 456,
})

local tasks = app.integrations.copper.list_tasks({
  page_size = 25,
  status = "open",
})

local task = app.integrations.copper.create_task({
  name = "Follow up",
  assignee_id = 333,
  related_resource = { type = "company", id = 456 },
})

Each project and task also has matching get, update, and delete tools.

Activities

local activities = app.integrations.copper.list_activities({
  page_size = 25,
  parent = { type = "person", id = 123 },
})

local activity = app.integrations.copper.create_activity({
  parent = { type = "person", id = 123 },
  type = { category = "user", id = 1 },
  details = "Discussed renewal timing.",
})

local types = app.integrations.copper.list_activity_types({})

Activities also support get_activity, update_activity, and delete_activity.

Users, Pipelines, And Metadata

local me = app.integrations.copper.get_current_user({})
local users = app.integrations.copper.list_users({ page_size = 50 })
local account = app.integrations.copper.get_account_details({})

local pipelines = app.integrations.copper.list_pipelines({})
local stages = app.integrations.copper.list_pipeline_stages({})
local stages_for_pipeline = app.integrations.copper.list_pipeline_stages_in_pipeline({
  pipeline_id = 10,
})

local lead_statuses = app.integrations.copper.list_lead_statuses({})
local sources = app.integrations.copper.list_customer_sources({})
local loss_reasons = app.integrations.copper.list_loss_reasons({})
local contact_types = app.integrations.copper.list_contact_types({})
local tags = app.integrations.copper.list_tags({})
local custom_fields = app.integrations.copper.list_custom_field_definitions({})

Webhooks

local hooks = app.integrations.copper.list_webhooks({})

local hook = app.integrations.copper.create_webhook({
  target = "https://example.test/hooks/copper",
  type = "person",
  event = "updated",
})

local fetched = app.integrations.copper.get_webhook({ id = 1001 })

app.integrations.copper.update_webhook({
  id = 1001,
  target = "https://example.test/hooks/copper-v2",
})

app.integrations.copper.delete_webhook({ id = 1001 })

Multi-Account

Hosts can expose account-scoped namespaces. The functions are identical; only credentials differ.

app.integrations.copper.default.list_contacts({ page_size = 10 })
app.integrations.copper.sales.list_opportunities({ page_size = 10 })

Raw agent markdown

# Copper CRM Lua API Reference

Namespace: `copper`

Copper calls contact records "People" in the official API. This package keeps the existing `contact` tool names for agent compatibility while routing them to Copper `/people` endpoints.

## Authentication

Copper requires:

- `api_key`
- `email`
- optional `url`, defaulting to `https://api.copper.com/developer_api/v1`

## People / Contacts

```lua
local people = app.integrations.copper.list_contacts({
  page_size = 25,
  page_number = 1,
  sort_by = "name",
})

local person = app.integrations.copper.get_contact({ id = 123 })

local by_email = app.integrations.copper.get_contact_by_email({
  email = "ada@example.test",
})

local created = app.integrations.copper.create_contact({
  name = "Ada Example",
  email = "ada@example.test",
})

local updated = app.integrations.copper.update_contact({
  id = 123,
  name = "Ada Lovelace",
})

app.integrations.copper.delete_contact({ id = 123 })
```

## Companies

```lua
local companies = app.integrations.copper.list_companies({
  page_size = 25,
  sort_by = "name",
})

local company = app.integrations.copper.get_company({ id = 456 })

local created = app.integrations.copper.create_company({
  name = "Example Corp",
})

app.integrations.copper.update_company({
  id = 456,
  details = "Enterprise account",
})

app.integrations.copper.delete_company({ id = 456 })
```

## Opportunities

```lua
local opportunities = app.integrations.copper.list_opportunities({
  page_size = 25,
  pipeline_ids = { 10 },
})

local opportunity = app.integrations.copper.get_opportunity({ id = 789 })

local created = app.integrations.copper.create_opportunity({
  name = "Example renewal",
  pipeline_id = 10,
})

app.integrations.copper.update_opportunity({
  id = 789,
  monetary_value = 250000,
  win_probability = 70,
})

app.integrations.copper.delete_opportunity({ id = 789 })
```

## Leads

```lua
local leads = app.integrations.copper.list_leads({
  page_size = 25,
  email = "buyer@example.test",
})

local lead = app.integrations.copper.get_lead({ id = 111 })

local created = app.integrations.copper.create_lead({
  name = "Buyer Example",
  company_name = "Example Corp",
  status_id = 222,
})

app.integrations.copper.update_lead({
  id = 111,
  details = "Qualified inbound lead",
})

app.integrations.copper.delete_lead({ id = 111 })
```

## Projects And Tasks

```lua
local projects = app.integrations.copper.list_projects({
  page_size = 25,
})

local project = app.integrations.copper.create_project({
  name = "Implementation",
  company_id = 456,
})

local tasks = app.integrations.copper.list_tasks({
  page_size = 25,
  status = "open",
})

local task = app.integrations.copper.create_task({
  name = "Follow up",
  assignee_id = 333,
  related_resource = { type = "company", id = 456 },
})
```

Each project and task also has matching `get`, `update`, and `delete` tools.

## Activities

```lua
local activities = app.integrations.copper.list_activities({
  page_size = 25,
  parent = { type = "person", id = 123 },
})

local activity = app.integrations.copper.create_activity({
  parent = { type = "person", id = 123 },
  type = { category = "user", id = 1 },
  details = "Discussed renewal timing.",
})

local types = app.integrations.copper.list_activity_types({})
```

Activities also support `get_activity`, `update_activity`, and `delete_activity`.

## Users, Pipelines, And Metadata

```lua
local me = app.integrations.copper.get_current_user({})
local users = app.integrations.copper.list_users({ page_size = 50 })
local account = app.integrations.copper.get_account_details({})

local pipelines = app.integrations.copper.list_pipelines({})
local stages = app.integrations.copper.list_pipeline_stages({})
local stages_for_pipeline = app.integrations.copper.list_pipeline_stages_in_pipeline({
  pipeline_id = 10,
})

local lead_statuses = app.integrations.copper.list_lead_statuses({})
local sources = app.integrations.copper.list_customer_sources({})
local loss_reasons = app.integrations.copper.list_loss_reasons({})
local contact_types = app.integrations.copper.list_contact_types({})
local tags = app.integrations.copper.list_tags({})
local custom_fields = app.integrations.copper.list_custom_field_definitions({})
```

## Webhooks

```lua
local hooks = app.integrations.copper.list_webhooks({})

local hook = app.integrations.copper.create_webhook({
  target = "https://example.test/hooks/copper",
  type = "person",
  event = "updated",
})

local fetched = app.integrations.copper.get_webhook({ id = 1001 })

app.integrations.copper.update_webhook({
  id = 1001,
  target = "https://example.test/hooks/copper-v2",
})

app.integrations.copper.delete_webhook({ id = 1001 })
```

## Multi-Account

Hosts can expose account-scoped namespaces. The functions are identical; only credentials differ.

```lua
app.integrations.copper.default.list_contacts({ page_size = 10 })
app.integrations.copper.sales.list_opportunities({ page_size = 10 })
```

Metadata-derived Lua example

local result = app.integrations.copper.list_contacts({page_size = 1, sort_by = "example_sort_by"})
print(result)

Functions

list_contacts Read

Search and list contacts in Copper CRM. Returns contact names, emails, and IDs.

Lua path: app.integrations.copper.list_contacts
Full name: copper.copper_list_contacts

Parameter	Type	Required	Description
`page_size`	integer	no	Number of contacts to return per page (default: 25, max: 200).
`sort_by`	string	no	Field to sort by (e.g., "name", "created_at").

get_contact Read

Get details of a specific contact in Copper CRM by ID.

Lua path: app.integrations.copper.get_contact
Full name: copper.copper_get_contact

Parameter	Type	Required	Description
`id`	integer	yes	The Copper contact ID.

get_contact_by_email Read

Get a Copper person by email.

Lua path: app.integrations.copper.get_contact_by_email
Full name: copper.copper_get_contact_by_email

Parameter	Type	Required	Description
No parameters.

create_contact Write

Create a new contact in Copper CRM. Provide at least a name.

Lua path: app.integrations.copper.create_contact
Full name: copper.copper_create_contact

Parameter	Type	Required	Description
`name`	string	yes	Full name of the contact.
`email`	string	no	Email address of the contact.

update_contact Write

Update an existing contact in Copper CRM. Only the fields provided will be updated.

Lua path: app.integrations.copper.update_contact
Full name: copper.copper_update_contact

Parameter	Type	Required	Description
`id`	integer	yes	The Copper contact ID to update.
`name`	string	no	Updated full name of the contact.
`email`	string	no	Updated email address.

delete_contact Write

Delete a contact from Copper CRM. This action cannot be undone.

Lua path: app.integrations.copper.delete_contact
Full name: copper.copper_delete_contact

Parameter	Type	Required	Description
`id`	integer	yes	The Copper contact ID to delete.

list_companies Read

Search and list companies in Copper CRM. Returns company names, domains, and IDs.

Lua path: app.integrations.copper.list_companies
Full name: copper.copper_list_companies

Parameter	Type	Required	Description
`page_size`	integer	no	Number of companies to return per page (default: 25, max: 200).
`sort_by`	string	no	Field to sort by (e.g., "name", "created_at").

get_company Read

Get details of a specific company in Copper CRM by ID.

Lua path: app.integrations.copper.get_company
Full name: copper.copper_get_company

Parameter	Type	Required	Description
`id`	integer	yes	The Copper company ID.

create_company Write

Create a new company in Copper CRM.

Lua path: app.integrations.copper.create_company
Full name: copper.copper_create_company

Parameter	Type	Required	Description
`name`	string	yes	Company name.

update_company Write

Update a company.

Lua path: app.integrations.copper.update_company
Full name: copper.copper_update_company

Parameter	Type	Required	Description
No parameters.

delete_company Write

Delete a company.

Lua path: app.integrations.copper.delete_company
Full name: copper.copper_delete_company

Parameter	Type	Required	Description
No parameters.

list_opportunities Read

Search and list opportunities (deals) in Copper CRM. Returns opportunity names, values, stages, and IDs.

Lua path: app.integrations.copper.list_opportunities
Full name: copper.copper_list_opportunities

Parameter	Type	Required	Description
`page_size`	integer	no	Number of opportunities to return per page (default: 25, max: 200).
`sort_by`	string	no	Field to sort by (e.g., "name", "created_at").

get_opportunity Read

Get details of a specific opportunity (deal) in Copper CRM by ID.

Lua path: app.integrations.copper.get_opportunity
Full name: copper.copper_get_opportunity

Parameter	Type	Required	Description
`id`	integer	yes	The Copper opportunity ID.

create_opportunity Write

Create a new opportunity (deal) in Copper CRM. Provide a name and pipeline ID. Use copper_list_pipelines first to find available pipeline IDs.

Lua path: app.integrations.copper.create_opportunity
Full name: copper.copper_create_opportunity

Parameter	Type	Required	Description
`name`	string	yes	Opportunity name.
`pipeline_id`	integer	yes	ID of the pipeline to create the opportunity in. Use copper_list_pipelines to find available IDs.

update_opportunity Write

Update an opportunity.

Lua path: app.integrations.copper.update_opportunity
Full name: copper.copper_update_opportunity

Parameter	Type	Required	Description
No parameters.

delete_opportunity Write

Delete an opportunity.

Lua path: app.integrations.copper.delete_opportunity
Full name: copper.copper_delete_opportunity

Parameter	Type	Required	Description
No parameters.

list_leads Read

Search and list leads.

Lua path: app.integrations.copper.list_leads
Full name: copper.copper_list_leads

Parameter	Type	Required	Description
No parameters.

get_lead Read

Get a lead by ID.

Lua path: app.integrations.copper.get_lead
Full name: copper.copper_get_lead

Parameter	Type	Required	Description
No parameters.

create_lead Write

Create a lead.

Lua path: app.integrations.copper.create_lead
Full name: copper.copper_create_lead

Parameter	Type	Required	Description
No parameters.

update_lead Write

Update a lead.

Lua path: app.integrations.copper.update_lead
Full name: copper.copper_update_lead

Parameter	Type	Required	Description
No parameters.

delete_lead Write

Delete a lead.

Lua path: app.integrations.copper.delete_lead
Full name: copper.copper_delete_lead

Parameter	Type	Required	Description
No parameters.

list_projects Read

Search and list projects.

Lua path: app.integrations.copper.list_projects
Full name: copper.copper_list_projects

Parameter	Type	Required	Description
No parameters.

get_project Read

Get a project by ID.

Lua path: app.integrations.copper.get_project
Full name: copper.copper_get_project

Parameter	Type	Required	Description
No parameters.

create_project Write

Create a project.

Lua path: app.integrations.copper.create_project
Full name: copper.copper_create_project

Parameter	Type	Required	Description
No parameters.

update_project Write

Update a project.

Lua path: app.integrations.copper.update_project
Full name: copper.copper_update_project

Parameter	Type	Required	Description
No parameters.

delete_project Write

Delete a project.

Lua path: app.integrations.copper.delete_project
Full name: copper.copper_delete_project

Parameter	Type	Required	Description
No parameters.

list_tasks Read

Search and list tasks.

Lua path: app.integrations.copper.list_tasks
Full name: copper.copper_list_tasks

Parameter	Type	Required	Description
No parameters.

get_task Read

Get a task by ID.

Lua path: app.integrations.copper.get_task
Full name: copper.copper_get_task

Parameter	Type	Required	Description
No parameters.

create_task Write

Create a task.

Lua path: app.integrations.copper.create_task
Full name: copper.copper_create_task

Parameter	Type	Required	Description
No parameters.

update_task Write

Update a task.

Lua path: app.integrations.copper.update_task
Full name: copper.copper_update_task

Parameter	Type	Required	Description
No parameters.

delete_task Write

Delete a task.

Lua path: app.integrations.copper.delete_task
Full name: copper.copper_delete_task

Parameter	Type	Required	Description
No parameters.

list_activities Read

Search and list activities.

Lua path: app.integrations.copper.list_activities
Full name: copper.copper_list_activities

Parameter	Type	Required	Description
No parameters.

get_activity Read

Get an activity by ID.

Lua path: app.integrations.copper.get_activity
Full name: copper.copper_get_activity

Parameter	Type	Required	Description
No parameters.

create_activity Write

Create an activity.

Lua path: app.integrations.copper.create_activity
Full name: copper.copper_create_activity

Parameter	Type	Required	Description
No parameters.

update_activity Write

Update an activity.

Lua path: app.integrations.copper.update_activity
Full name: copper.copper_update_activity

Parameter	Type	Required	Description
No parameters.

delete_activity Write

Delete an activity.

Lua path: app.integrations.copper.delete_activity
Full name: copper.copper_delete_activity

Parameter	Type	Required	Description
No parameters.

list_activity_types Read

List activity types.

Lua path: app.integrations.copper.list_activity_types
Full name: copper.copper_list_activity_types

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Get the currently authenticated Copper CRM user. Useful for verifying the connection and account context.

Lua path: app.integrations.copper.get_current_user
Full name: copper.copper_get_current_user

Parameter	Type	Required	Description
No parameters.

list_users Read

Search and list users.

Lua path: app.integrations.copper.list_users
Full name: copper.copper_list_users

Parameter	Type	Required	Description
No parameters.

get_user Read

Get a user by ID.

Lua path: app.integrations.copper.get_user
Full name: copper.copper_get_user

Parameter	Type	Required	Description
No parameters.

get_account_details Read

Get account details.

Lua path: app.integrations.copper.get_account_details
Full name: copper.copper_get_account_details

Parameter	Type	Required	Description
No parameters.

list_pipelines Read

List all sales pipelines in Copper CRM. Each pipeline contains stages that opportunities move through.

Lua path: app.integrations.copper.list_pipelines
Full name: copper.copper_list_pipelines

Parameter	Type	Required	Description
No parameters.

list_pipeline_stages Read

List pipeline stages.

Lua path: app.integrations.copper.list_pipeline_stages
Full name: copper.copper_list_pipeline_stages

Parameter	Type	Required	Description
No parameters.

list_stages_pipeline Read

List stages in one pipeline.

Lua path: app.integrations.copper.list_stages_pipeline
Full name: copper.copper_list_pipeline_stages_in_pipeline

Parameter	Type	Required	Description
No parameters.

list_lead_statuses Read

List lead statuses.

Lua path: app.integrations.copper.list_lead_statuses
Full name: copper.copper_list_lead_statuses

Parameter	Type	Required	Description
No parameters.

list_customer_sources Read

List customer sources.

Lua path: app.integrations.copper.list_customer_sources
Full name: copper.copper_list_customer_sources

Parameter	Type	Required	Description
No parameters.

list_loss_reasons Read

List opportunity loss reasons.

Lua path: app.integrations.copper.list_loss_reasons
Full name: copper.copper_list_loss_reasons

Parameter	Type	Required	Description
No parameters.

list_contact_types Read

List contact types.

Lua path: app.integrations.copper.list_contact_types
Full name: copper.copper_list_contact_types

Parameter	Type	Required	Description
No parameters.

Parameter	Type	Required	Description
No parameters.

list_custom_field_definitions Read

List custom field definitions.

Lua path: app.integrations.copper.list_custom_field_definitions
Full name: copper.copper_list_custom_field_definitions

Parameter	Type	Required	Description
No parameters.

list_webhooks Read

List webhook subscriptions.

Lua path: app.integrations.copper.list_webhooks
Full name: copper.copper_list_webhooks

Parameter	Type	Required	Description
No parameters.

get_webhook Read

Get a webhook subscription.

Lua path: app.integrations.copper.get_webhook
Full name: copper.copper_get_webhook

Parameter	Type	Required	Description
No parameters.

create_webhook Write

Create a webhook subscription.

Lua path: app.integrations.copper.create_webhook
Full name: copper.copper_create_webhook

Parameter	Type	Required	Description
No parameters.

update_webhook Write

Update a webhook subscription.

Lua path: app.integrations.copper.update_webhook
Full name: copper.copper_update_webhook

Parameter	Type	Required	Description
No parameters.

delete_webhook Write

Delete a webhook subscription.

Lua path: app.integrations.copper.delete_webhook
Full name: copper.copper_delete_webhook

Parameter	Type	Required	Description
No parameters.