Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Copper CRM MCP Server What deals are closing this month in my main pipeline?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets an AI agent (Claude Desktop, or any MCP client) read your Copper CRM and run light pipeline hygiene — search deals, spot stale opportunities, log a note, and schedule a follow-up.
Unofficial. Built to show what an official Copper MCP server could look like. It's a focused, read-heavy demo — not a production integration.
Read-heavy by design. Six of the seven tools only read. Exactly one tool
writes (log_activity), and even that only appends an activity — it can't
edit or delete existing records. A deliberately small blast radius is the
right security posture for letting an agent touch your CRM.
Descriptions written for an agent. Each tool says what it returns and when
to reach for it, so the model chains them correctly (e.g. call list_pipelines
to turn a stage name into the IDs the other tools need).
Clean errors, not stack traces. A bad key comes back as
Copper API returned 401 — check COPPER_API_KEY, so the agent can explain the
problem instead of choking on it.
Related MCP server: AI-Assisted CRM MCP Server
git clone https://github.com/hasankhadra/copper-mcp.git
cd copper-mcp
npm install && npm run buildThen add this block to your Claude Desktop config
(~/Library/Application Support/Claude/claude_desktop_config.json on macOS),
and restart Claude Desktop:
{
"mcpServers": {
"copper": {
"command": "node",
"args": ["/absolute/path/to/copper-mcp/dist/index.js"],
"env": {
"COPPER_API_KEY": "your_copper_api_key",
"COPPER_USER_EMAIL": "you@yourcompany.com"
}
}
}
}Get your API key from Copper under Settings → Integrations → API Keys. The
COPPER_USER_EMAIL must be the email of the user who owns that key.
Tool | Reads / Writes | What it does |
| read | Find people by name or email. |
| read | Find companies by name. |
| read | List/filter deals by pipeline, stage, or assignee. |
| read | Every pipeline and its stages — maps stage names → IDs. |
| read | Full detail of one deal (custom fields, tags, contact). |
| write* | Schedule a follow-up task, optionally linked to a record. |
| write | Append a note/call to a person, company, opportunity, or lead. |
* create_task creates a new task record; it never modifies existing CRM data.
log_activity is the only tool that writes onto an existing record.
Once it's wired into Claude Desktop, ask:
"Which deals in my main pipeline are closing this month and have had no activity in the last 2 weeks? Log a note on the top one reminding me to send pricing, and create a follow-up task for Friday."
The agent calls list_pipelines → search_opportunities → get_opportunity to
triage, then log_activity + create_task to act.
Read from the environment (never hardcoded):
Variable | Description |
| Your Copper API key. |
| Email of the key's owner. |
For local testing outside Claude Desktop, copy .env.example to .env and run
COPPER_API_KEY=... COPPER_USER_EMAIL=... npm start.
npm run build # compile TypeScript → dist/
npm run dev # tsc --watch
npm start # run the built server on stdioLayout: src/copperClient.ts is the single HTTP/auth/error layer; each tool
lives in its own file under src/tools/; src/index.ts registers them and
opens the stdio transport.
Built by Hasan Khadra — hk@hasankhadra.me · hasankhadra.me.
The official version ships with full OAuth 2.1, write coverage across the CRM, and a two-week fixed-scope delivery.
Create a follow-up task in Copper, optionally linked to a person, company, or opportunity. Use this to schedule a reminder (e.g. 'send pricing on Friday'). Returns the created task. This tool creates a task record but does not modify any existing CRM data.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The task title, e.g. 'Send pricing to Acme'. | |
| details | No | Free-text notes / description for the task. | |
| due_date | No | Due date in ISO format, e.g. '2026-07-17'. | |
| related_resource | No | Optionally link the task to a CRM record. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool creates a task without modifying existing CRM data and mentions the return value. It could further describe side effects on linked resources, but the current level is adequate for a creation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and contains no superfluous information. Every sentence serves a clear role.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool without output schema, the description covers purpose, inputs, side-effects, and return value. It could mention error conditions or idempotency, but these are not essential given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents parameters well. The description adds value by contextualizing the tool's use (scheduling reminders) and hinting at optional linking. It does not redundantly repeat schema details but provides enough additional meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a follow-up task in Copper, optionally linked to CRM records. It provides a specific usage example (schedule a reminder) and distinguishes itself from sibling tools which are for searching, listing, or getting records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete use case ('schedule a reminder') with an example. However, it does not explicitly state when not to use this tool or mention alternatives. The sibling tools are sufficiently different to imply usage context, but explicit exclusions would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full detail of a single opportunity (deal) by its id — including custom fields, tags, status, monetary value, close date, primary contact, and the last activity dates you need to spot stale deals. Use this after search_opportunities to drill into one deal.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The Copper opportunity id (from search_opportunities). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It details what is returned (custom fields, tags, status, etc.) and the purpose (spot stale deals). It does not explicitly mention idempotency or side effects, but it is clearly a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and key details, no superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and no output schema; description adequately covers what the tool returns and its use case, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, baseline 3. Description adds value by specifying the id comes from 'search_opportunities', providing source context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Fetch' and resource 'single opportunity (deal)', lists returned fields (custom fields, tags, status, monetary value, close date, primary contact, last activity dates), and explicitly distinguishes from sibling search_opportunities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly states when to use: 'Use this after search_opportunities to drill into one deal.' Provides clear context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every sales pipeline in Copper along with its ordered stages. Call this first when you need to map a human stage or pipeline name (e.g. 'Closing this month') to the numeric IDs that search_opportunities and get_opportunity use. Returns each pipeline's id and name, plus each stage's id, name, and win_probability. Takes no arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description notes the tool takes no arguments and returns specific fields (id, name for pipelines; id, name, win_probability for stages). Being a listing operation with no side effects, this provides sufficient behavioral transparency despite no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences succinctly cover purpose, usage context, and output structure with no unnecessary words. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple return, the description fully explains the output structure and why the tool is useful (mapping names to IDs). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema, so description does not need to add parameter semantics. Baseline score of 4 applies as per guidelines for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists every sales pipeline with ordered stages, uses specific verb 'list' and resource 'pipelines', and distinguishes from siblings by noting its use for mapping names to IDs needed by other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call this tool first for mapping human pipeline/stage names to numeric IDs used by sibling tools. Though no explicit when-not-to-use, the use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log a note or call activity onto a person, company, opportunity, or lead in Copper. This is the only tool that writes to the CRM — it APPENDS an activity (it never edits or deletes existing data). Use it to record a call summary or leave a reminder note on a record. Defaults to a 'Note' activity. Returns the created activity.
| Name | Required | Description | Default |
|---|---|---|---|
| parent | Yes | The CRM record this activity is logged on. | |
| details | Yes | The note / activity text to record. | |
| activity_type_id | No | Copper activity type id. Defaults to 0 (Note). Other user-defined types can be found via the Copper UI; leave unset to log a plain note. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool only appends (never edits or deletes), returns the created activity, and defaults to a 'Note' activity. This is good but could be enhanced by mentioning potential constraints (e.g., maximum length of details) or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, no redundancy, and front-loads the essential purpose and behavior. Every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and no output schema, the description covers purpose, behavior, and return value. It could be more complete by mentioning that the parent must exist in the CRM, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds value by explaining the default for activity_type_id ('defaults to Note') and the usage of details as 'note / activity text'. It also provides context for the parent parameter as the CRM record.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'log', the resource 'activity', and the scope (person, company, opportunity, lead). It distinguishes itself from sibling tools by claiming it is 'the only tool that writes to the CRM'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use (record call summary or leave a reminder note) and explicitly states it is the only write tool, implying that siblings are read-only. However, it does not explicitly list when not to use or provide alternative tools for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find companies (accounts) in Copper by name. Use this to resolve a company before filtering opportunities or logging an activity against it. Returns a list of matches, each with id, name, domain, and primary phone. If no name is given it returns the most recent companies.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Full or partial company name to search for, e.g. 'Dunder Mifflin'. | |
| page_size | No | Maximum number of companies to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. Discloses that omitting name returns most recent companies. Implies read-only nature. Could add details about pagination or ordering, but sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no redundancy. Each sentence adds essential information: purpose, usage advice, return structure and default behavior. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains return fields (id, name, domain, primary phone) and handles the no-name edge case. Provides enough context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value: clarifies name as partial, states default page_size (10) not in schema, and explains return fields. Exceeds schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Find companies (accounts) in Copper by name' with a specific verb and resource. It distinguishes from sibling tools like search_people and search_opportunities by specifying the entity type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Use this to resolve a company before filtering opportunities or logging an activity against it.' Lacks explicit when-not or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List and filter opportunities (deals) in Copper. Filter by pipeline, stage, or assignee to triage a book of business. Returns each deal's id, name, monetary_value, pipeline_id, pipeline_stage_id, close_date, company_name, and assignee_id. It also returns date_last_contacted (the last call/meeting/email date) and interaction_count, so you can spot stale deals directly from this one call without fetching each opportunity. Stage and pipeline are returned as IDs — call list_pipelines to map them to names. Use get_opportunity for the full record (custom fields, tags, contacts).
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Maximum number of opportunities to return (default 20). | |
| assignee_id | No | Restrict to deals owned by a specific Copper user. | |
| pipeline_id | No | Restrict to a single pipeline (get IDs from list_pipelines). | |
| pipeline_stage_id | No | Restrict to a single stage within a pipeline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It lists return fields including derived ones (date_last_contacted, interaction_count) and notes that IDs need mapping. It does not explicitly state the tool is read-only, but the context implies it. Slight gap on pagination/rate limits, but schema covers page_size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the main action and resource. Every sentence adds value: filtering, return fields, and cross-references to siblings. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 optional parameters and no output schema, the description fully covers return fields, relationships to other tools, and a concrete use case (stale deals). No critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with decent parameter descriptions. The description adds context (e.g., pipeline_id refers to list_pipelines) but does not significantly expand on the parameter semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List and filter') with a clear resource ('opportunities (deals) in Copper'). It distinguishes from siblings by mentioning that get_opportunity returns full records and list_pipelines maps IDs, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance ('triage a book of business', 'spot stale deals') and when-not-to-use ('Use get_opportunity for the full record', 'call list_pipelines to map them to names'). This helps the agent choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find people (contacts) in Copper by name and/or email address. Use this to look up a contact before logging an activity or creating a task against them. Returns a list of matches, each with id, name, primary email, company_name, and title. If no filters are given it returns the most recent people.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Full or partial name to search for, e.g. 'Jim Halpert'. | |
| No | Exact email address to search for. | ||
| page_size | No | Maximum number of people to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses return format ('Returns a list of matches, each with id, name, primary email, company_name, and title') and default behavior ('If no filters are given it returns the most recent people'). This is sufficient for a search tool with no destructive side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, no redundancy, and front-loaded with the core purpose. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return fields adequately. It covers default behavior and the purpose of all parameters implicitly. Could note the default page_size (10) but schema handles that. Overall, it is complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema: it notes 'full or partial name' and 'exact email' but does not elaborate further. The page_size parameter is fully described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find people (contacts) in Copper by name and/or email address.' It specifies the resource (people) and the method (search), effectively distinguishing it from sibling tools like search_companies and search_opportunities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: 'Use this to look up a contact before logging an activity or creating a task against them.' It implies when to use this tool, though it does not explicitly state when not to use or mention alternatives. However, the sibling tools list provides some differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_taskget_opportunitylist_pipelineslog_activitysearch_companiessearch_opportunitiessearch_peopleScored across 7 tools
Each tool targets a distinct resource and action (tasks, opportunities, pipelines, activities, companies, people). No overlap in functionality; agents can easily distinguish between searching, fetching, creating, and logging.
All tool names use snake_case and follow a clear verb_noun pattern (e.g., create_task, search_opportunities, list_pipelines). The naming is consistent and predictable.
With 7 tools, the server is well-scoped for a CRM focus. Each tool serves a distinct purpose, and the count falls comfortably within the typical 3-15 range.
The server covers search and read operations for people, companies, and opportunities, and allows creating tasks and logging activities. However, it lacks tools to create, update, or delete core CRM records (opportunities, companies, people), leaving significant lifecycle gaps.
Connect AI to your Attio CRM. Manage contacts, companies, deals, and sales pipelines. Create tasks…
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
Open-source CRM your AI agents can write to: companies, people, deals, tasks, notes, pipeline.
Connect AI assistants to Nimble CRM to access and work with customer relationship data.
