Summary
Connects Claude to your Attio CRM workspace through 19 universal operations covering the full API surface. You get complete CRUD for companies, people, deals, tasks, lists, and notes, plus batch operations, advanced filtering with AND/OR logic, and relationship navigation between contacts and pipeline stages. The implementation consolidates what used to be 40+ resource-specific tools into universal operations like search_records and batch_records, with scoped helpers for high-frequency writes like create_deal and update_company. Includes a workspace schema discovery tool that generates Claude skills from your actual field names to prevent "wrong field" errors. Reach for this when you need to query prospects, update pipelines, or automate CRM workflows through natural language instead of clicking through Attio's UI.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
34 tools
create-commentCreates a new comment on a record, list entry, or as a reply to an existing comment thread. Provide exactly one of: (parent_object + parent_record_id) for records, (parent_list + parent_entry_id) for list entries, or (parent_comment_id) for replies. Email addresses in the cont...6 params
Creates a new comment on a record, list entry, or as a reply to an existing comment thread. Provide exactly one of: (parent_object + parent_record_id) for records, (parent_list + parent_entry_id) for list entries, or (parent_comment_id) for replies. Email addresses in the cont...
Parameters* required
contentstringThe comment content as plain text. Email addresses in the text will be automatically converted to @mentions if they match workspace members.
example: Great work on this deal! cc team@example.com
parent_liststringCreate comment on a list entry. The list the entry belongs to. Must be provided with parent_entry_id.
format: slug or UUID
example: "my_list", "bb9d278b-bfa9-4b5c-b67c-f2553ee2d461"
parent_objectstringCreate comment on a record. The object the record belongs to. Must be provided with parent_record_id.
format: slug or UUID
example: "people", "companies", "a55dd58d-d8ff-4ddf-84e0-a54a260edb93"
parent_entry_idstringCreate comment on a list entry. The entry ID. Must be provided with parent_list.
example: 1a942b81-3901-44d4-919f-afd025578d51
parent_record_idstringCreate comment on a record. The record ID. Must be provided with parent_object.
example: 370b4e08-7084-47dc-b7ca-d41dda762da9
parent_comment_idstringReply to an existing comment thread. The ID of the parent comment. Cannot be a reply - must be a top-level comment.
example: a19f759a-964c-4199-8c32-296d7cbf1ee8
add-record-to-listAdd a record to a list as a new list entry. IMPORTANT: Before calling this tool: 1) You should call list-list-attribute-definitions for the target list to understand which entry attributes are available. 2) You should call list-records or search-records to find the record you...5 params
Add a record to a list as a new list entry. IMPORTANT: Before calling this tool: 1) You should call list-list-attribute-definitions for the target list to understand which entry attributes are available. 2) You should call list-records or search-records to find the record you...
Parameters* required
liststringThe ID or slug of the list to add the entry to.
format: slug or UUID
example: "sales_pipeline", "143bffde-8102-460a-8fe8-db2d9c107159"
entry_valuesobjectOptional attribute values for the list entry. Use `api_slug` or `attribute_id` from `list-list-attribute-definitions` as the key.
# VALUE FORMATS BY ATTRIBUTE TYPE:
* text: String - "name": "Acme Corp"
* number: Number - "employee_count": 100
* checkbox: Boolean - "is_active": true
* date: ISO 8601 date - "founded_date": "2024-01-15"
* timestamp: ISO 8601 datetime - "created_at": "2024-01-15T10:30:00Z"
* rating: Number 0-5 - "priority": 3
* email_address: String or array of strings (depends on is_multiselect) - "email_addresses": ["alice@example.com"]
* phone_number: String or array of strings (depends on is_multiselect) - "phone_numbers": ["+14155551234"]
* domain: String or array of strings (depends on is_multiselect) - "domains": ["example.com", "attio.com"]
* select: Option title or UUID - "industry": "Software"
* status: Status title or UUID - "stage": "In Progress"
* currency: Number (uses attribute's configured currency) - "deal_value": 10000
* location: Address string - "address": "1 Infinite Loop, Cupertino, CA, 95014, US"
Or object - {"line_1": "1 Infinite Loop", "locality": "Cupertino", "region": "CA", "postcode": "95014", "country_code": "US", "latitude": "37.331741", "longitude": "-122.030333"}
* personal_name: "Lastname, Firstname" format (note: last name comes FIRST) - "contact_name": "Doe, John"
Or object with ALL THREE required fields: [{"first_name": "John", "last_name": "Doe", "full_name": "John Doe"}]
* actor_reference: Workspace member by email or UUID - "owner": "user@example.com"
* interaction: NOT WRITABLE - this attribute type cannot be set via the API
# RECORD REFERENCES (linking to other records):
Record reference attributes link to records in other objects (e.g., linking a deal to a company).
Formats supported:
1. By record ID: {"target_object": "companies", "target_record_id": "<uuid>"}
2. By matching attribute (must contain exactly ONE matching value):
{"target_object": "people", "email_addresses": [{"email_address": "alice@example.com"}]}
The key (e.g. "email_addresses") is an attribute slug on the target object.
3. Simple format (only if attribute references a single object type):
- For people: pass an email address - "contact": "alice@example.com" (matches by email)
- For companies: pass a domain - "company": "acme.com" (matches by domain)
- Otherwise: pass a record UUID - "related_record": "<uuid>"
# ARRAYS VS SINGLE VALUES:
For attributes with is_multiselect=true, always provide an array.
For single-value attributes, you can use either format: "name": "value" or "name": ["value"]
parent_objectstringThe object type of the parent record being added to the list.
format: slug or UUID
example: "companies", "people", "a6bd01e1-550b-45ac-9b6f-62bf37af0a0b"
allow_duplicatesbooleanWhether to allow adding a record that already exists in the list. Defaults to false, which prevents duplicate entries and returns an error with the existing entry ID instead.default: false
parent_record_idstringThe ID of the record to add to the list.
example: d94d9fdb-f3b3-4320-a4cc-c4e9ce3ac1a9
create-noteCreates a new note attached to a record. Returns the created note's ID.5 params
Creates a new note attached to a record. Returns the created note's ID.
Parameters* required
titlestringThe title of the note.
example: Q1 Planning Meeting Notes
contentstringThe body of the note in markdown format.
format: Markdown. Supports: headings (#, ##, ###), lists (-, *, 1.), bold (**), italic (*), strikethrough (~~), highlight (==), links ([text](url)). Code blocks, images, and tables are not supported.
example: ## Summary\n\nDiscussed **roadmap** priorities.
meeting_idstringOptional ID to link to a specific meeting.
example: 15f9db79-5b7e-4c09-92f5-f0807e2bea60
parent_objectstringThe object type for the parent record.
format: slug or UUID
example: "people", "companies", "6b363357-021a-4c92-9e24-47d6995d05c1"
parent_record_idstringThe record ID to attach the note to.
example: 4231c20a-029c-448b-afe2-39802fede04a
create-recordCreate a new record in a given object. IMPORTANT: Before calling this tool, you should call list-attribute-definitions for the target object to understand which attributes are available, their types, whether they are required, and (for select/status fields) the valid options....2 params
Create a new record in a given object. IMPORTANT: Before calling this tool, you should call list-attribute-definitions for the target object to understand which attributes are available, their types, whether they are required, and (for select/status fields) the valid options....
Parameters* required
objectstringThe ID or slug of the object to create the record in.
format: slug or UUID
example: "companies", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
valuesobjectAn object mapping attribute slugs or IDs to values. Use `api_slug` or `attribute_id` from `list-attribute-definitions` as the key.
# VALUE FORMATS BY ATTRIBUTE TYPE:
* text: String - "name": "Acme Corp"
* number: Number - "employee_count": 100
* checkbox: Boolean - "is_active": true
* date: ISO 8601 date - "founded_date": "2024-01-15"
* timestamp: ISO 8601 datetime - "created_at": "2024-01-15T10:30:00Z"
* rating: Number 0-5 - "priority": 3
* email_address: String or array of strings (depends on is_multiselect) - "email_addresses": ["alice@example.com"]
* phone_number: String or array of strings (depends on is_multiselect) - "phone_numbers": ["+14155551234"]
* domain: String or array of strings (depends on is_multiselect) - "domains": ["example.com", "attio.com"]
* select: Option title or UUID - "industry": "Software"
* status: Status title or UUID - "stage": "In Progress"
* currency: Number (uses attribute's configured currency) - "deal_value": 10000
* location: Address string - "address": "1 Infinite Loop, Cupertino, CA, 95014, US"
Or object - {"line_1": "1 Infinite Loop", "locality": "Cupertino", "region": "CA", "postcode": "95014", "country_code": "US", "latitude": "37.331741", "longitude": "-122.030333"}
* personal_name: "Lastname, Firstname" format (note: last name comes FIRST) - "contact_name": "Doe, John"
Or object with ALL THREE required fields: [{"first_name": "John", "last_name": "Doe", "full_name": "John Doe"}]
* actor_reference: Workspace member by email or UUID - "owner": "user@example.com"
* interaction: NOT WRITABLE - this attribute type cannot be set via the API
# RECORD REFERENCES (linking to other records):
Record reference attributes link to records in other objects (e.g., linking a deal to a company).
Formats supported:
1. By record ID: {"target_object": "companies", "target_record_id": "<uuid>"}
2. By matching attribute (must contain exactly ONE matching value):
{"target_object": "people", "email_addresses": [{"email_address": "alice@example.com"}]}
The key (e.g. "email_addresses") is an attribute slug on the target object.
3. Simple format (only if attribute references a single object type):
- For people: pass an email address - "contact": "alice@example.com" (matches by email)
- For companies: pass a domain - "company": "acme.com" (matches by domain)
- Otherwise: pass a record UUID - "related_record": "<uuid>"
# ARRAYS VS SINGLE VALUES:
For attributes with is_multiselect=true, always provide an array.
For single-value attributes, you can use either format: "name": "value" or "name": ["value"]
example: {"actor_reference_by_id":"67be5dad-575b-495f-b9a7-57e663be9852","actor_reference_by_email":"user@example.com","checkbox":true,"currency":13.37,"date":"2012-12-12","domain":["example.com","sub.example.com"],"email_address":["hello@example.com"],"location_simple_format":"1 Infinite Loop, Cupertino, CA, 95014, US","location_object_format":{"line_1":"1 Infinite Loop","locality":"Cupertino","region":"CA","postcode":"95014","country_code":"US","latitude":"37.331741","longitude":"-122.030333"},"number":1337,"personal_name_simple_format":"Smith, John","personal_name_object_format":{"first_name":"John","last_name":"Smith","full_name":"John Owen Smith"},"rating":3,"rating_min":0,"rating_max":5,"record_reference_by_id":[{"target_object":"companies","target_record_id":"fea1460c-cba2-4aac-bccb-9d6fa1518e74"}],"record_reference_by_value":[{"target_object":"people","email_addresses":[{"email_address":"test@example.com"}]}],"select":"Select option 1","select_multiselect":["Select option 1","Select option 2"],"text":"Text value","timestamp":"2012-12-12T12:12:121Z","7bcef5b9-6254-41e5-8ec6-1fcb93c87574":"Example text value attribute referenced by ID","name":"Acme Corp","industry":"Software","employee_count":100,"primary_contact":"Doe, John","email_addresses":["contact@acme.com"],"associated_company":[{"target_object":"companies","target_record_id":"46cc9100-e0f0-4ca9-ac14-138cfe38de67"}]}
create-taskCreates a new task in Attio. Tasks can optionally have a deadline, an assignee (workspace member), and be linked to a record (e.g., a person or company). To assign to a workspace member, provide their workspace_member_id. To link to a record, provide both the object type (e.g....6 params
Creates a new task in Attio. Tasks can optionally have a deadline, an assignee (workspace member), and be linked to a record (e.g., a person or company). To assign to a workspace member, provide their workspace_member_id. To link to a record, provide both the object type (e.g....
Parameters* required
contentstringThe text content of the task. MUST be provided.
example: Follow up on current software solutions
deadline_atstringThe deadline date for the task.
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-02-15T00:00:00.000Z
is_completedbooleanWhether the task is completed. Defaults to false.
example: falsedefault: false
linked_record_idstringThe record ID to link the task to. Must be provided with linked_record_object.
example: 492c42ea-4def-4e51-9d1b-9ce24fc9e57f
linked_record_objectstringThe object type for the linked record. Must be provided with linked_record_id.
format: slug or UUID
example: "people", "companies"
assignee_workspace_member_idstringThe workspace member ID to assign the task to. Only one assignee can be specified via MCP.
example: 31abd9d6-667f-4240-b995-717be5ad126e
delete-commentDeletes a comment. You can only delete comments that you created. Deleting a parent comment will also delete all of its replies.1 params
Deletes a comment. You can only delete comments that you created. Deleting a parent comment will also delete all of its replies.
Parameters* required
comment_idstringThe ID of the comment to delete.
example: 6a1fd7b2-1858-4959-8b93-50e4d6ce7fc2
get-call-recordingRetrieves the full details of a call recording by ID, including its status, timestamps, and complete transcript.2 params
Retrieves the full details of a call recording by ID, including its status, timestamps, and complete transcript.
Parameters* required
meeting_idstringThe ID of the meeting that the call recording is associated with.
example: 4e377c73-1429-4171-bc94-cef68f9bdf07
call_recording_idstringThe ID of the call recording to retrieve.
example: 0e396018-1565-41fd-b4c8-2696b6bd187d
get-email-contentRetrieves the full content/body of an email. Requires the mailbox_id and email_header_id, which can be obtained from email search results.2 params
Retrieves the full content/body of an email. Requires the mailbox_id and email_header_id, which can be obtained from email search results.
Parameters* required
email_idstringThe ID of the email to retrieve content for.
example: 7fc117fa-0e5e-4bd8-a3ef-c00e060d8342
mailbox_idstringThe ID of the mailbox containing the email.
example: 532c82da-d3bc-4101-bb06-b8fd04a1326e
get-note-bodyGet the body of a note by its ID1 params
Get the body of a note by its ID
Parameters* required
note_idstringThe ID of the note to get the body of.
example: 1f06d2aa-bc46-4415-a030-b5ec054bd1e3
get-records-by-idsRetrieve a given set of records by their IDs for a given object. Returns an array of records with their attribute values. If a record is not found, it will not be included in the response.2 params
Retrieve a given set of records by their IDs for a given object. Returns an array of records with their attribute values. If a record is not found, it will not be included in the response.
Parameters* required
objectstringThe ID or slug of the object for which to retrieve records.
format: slug or UUID
example: "companies", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
record_idsarrayThe IDs of the records to retrieve. Records that are not found will not be included in the response.
example: ["ad27ac5f-95ab-4cc6-8880-e2655a1aae69", "d2e13173-1b77-48b3-ab1e-cf508f43c73e"]
list-attribute-definitionsList attribute definitions for a given object5 params
List attribute definitions for a given object
Parameters* required
limitnumberMaximum number of results to return.default: 10
queryvaluePlain text search term for fuzzy matching attribute titles and descriptions. If not specified or null, returns all attributes.
objectstringThe ID or slug of the object for which to retrieve attribute definitions.
format: slug or UUID
example: "companies", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
offsetnumberNumber of results to skip for pagination.default: 0
include_archivedbooleanIf true, the response will include archived attributes.default: false
list-comment-repliesLists replies to a comment. Provide the comment_id of a top-level comment to fetch its replies. Cannot be used with reply comments - only top-level comments that were created on records or list entries. All replies in a thread use the same parent comment ID.3 params
Lists replies to a comment. Provide the comment_id of a top-level comment to fetch its replies. Cannot be used with reply comments - only top-level comments that were created on records or list entries. All replies in a thread use the same parent comment ID.
Parameters* required
limitnumberMaximum number of replies to return.default: 20
offsetnumberNumber of results to skip for pagination.default: 0
comment_idstringThe ID of the parent comment thread to list replies for. Must be a top-level comment, not a reply.
example: 685a19b7-240b-44ec-8730-60e4f8731b20
list-commentsLists comments on a record or list entry. Returns paginated top-level comments with up to 5 replies each. If a thread has more replies, use "list-comment-replies" to fetch additional replies. Provide either (parent_object and parent_record_id) to list comments on a record, or...6 params
Lists comments on a record or list entry. Returns paginated top-level comments with up to 5 replies each. If a thread has more replies, use "list-comment-replies" to fetch additional replies. Provide either (parent_object and parent_record_id) to list comments on a record, or...
Parameters* required
limitnumberMaximum number of top-level comments to return.default: 10
offsetnumberNumber of results to skip for pagination.default: 0
parent_liststringFilter to comments on a specific list entry. The list the entry belongs to. Must be provided with parent_entry_id.
format: slug or UUID
example: "my_list", "543803fd-7ef8-4e29-af8d-83351ef99880"
parent_objectstringFilter to comments on a specific record. The object the record belongs to. Must be provided with parent_record_id.
format: slug or UUID
example: "people", "companies", "e6c0c8c9-488b-4aff-806f-d4d4dd3bc81f"
parent_entry_idstringFilter to comments on a specific list entry. The entry ID. Must be provided with parent_list.
example: 1dbf2c25-493b-4bfb-a1b8-6ed2e7b26ba9
parent_record_idstringFilter to comments on a specific record. The record ID. Must be provided with parent_object.
example: 97c10634-da0e-4a2f-9c2b-e2077382f7c6
list-list-attribute-definitionsList attribute definitions for a given list5 params
List attribute definitions for a given list
Parameters* required
liststringThe ID or slug of the list for which to retrieve attribute definitions.
format: slug or UUID
example: "sales_pipeline", "be2b24ee-4a8e-41be-a8d8-0cbb7de1a984"
limitnumberMaximum number of results to return.default: 10
queryvaluePlain text search term for fuzzy matching attribute titles and descriptions. If not specified or null, returns all attributes.
offsetnumberNumber of results to skip for pagination.default: 0
include_archivedbooleanIf true, the response will include archived attributes.default: false
list-listsList all lists in the Attio workspace. Returns list metadata including ID, name, API slug, and parent object types. Use the query parameter to filter by name or slug.3 params
List all lists in the Attio workspace. Returns list metadata including ID, name, API slug, and parent object types. Use the query parameter to filter by name or slug.
Parameters* required
limitnumberMaximum number of results to return.default: 10
querystringFilter returned lists using fuzzy search against list name or API slug. If null or not provided, returns all lists.
example: "sales pipeline"
offsetnumberNumber of results to skip for pagination.default: 0
list-records-in-listList entries in a given list with optional filtering and sorting. Returns paginated results. Use this tool to retrieve entries within a list that match specific criteria. You can filter on attributes using comparison operators, combine filters with AND/OR logic, and sort resul...5 params
List entries in a given list with optional filtering and sorting. Returns paginated results. Use this tool to retrieve entries within a list that match specific criteria. You can filter on attributes using comparison operators, combine filters with AND/OR logic, and sort resul...
Parameters* required
liststringThe list to query entries from.
format: slug or UUID
example: "my-sales-pipeline", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
limitnumberMaximum number of entries to return (max 50).default: 10
sortsarraySorting to apply (max 2). If empty, results are returned in a deterministic random order. Sortable types: text, number, currency, date, timestamp, checkbox, rating, domain, email_address, phone_number, personal_name.
example: [{"attribute": "name", "direction": "asc"}]
filtervalueFilter criteria to apply. If null, returns all entries. Filter syntax supports three types:
1. Single condition: {"attribute":"name", "op":"eq", "value":"Acme Corp"}
2. AND group (all must match): {"and": [{"attribute":"industry", "op":"eq", "value":"Technology"}, {"attribute":"employee_count", "op":"gte", "value":50}]}
3. OR group (any must match): {"or": [{"attribute":"stage", "op":"eq", "value":"Proposal"}, {"attribute":"stage", "op":"eq", "value":"Negotiation"}]}
Groups can be nested. Available operators by type:
- text: eq, neq, contains, not-contains, starts-with, ends-with
- number/currency/rating: eq, neq, gt, gte, lt, lte
- date: eq, neq, gt, gte, lt, lte (YYYY-MM-DD format, e.g. "2024-03-15")
- timestamp: eq, neq, gt, gte, lt, lte (full ISO 8601 with timezone preferred, e.g. "2024-03-15T14:30:00Z". Bare dates default to midnight UTC)
- checkbox: eq, neq (boolean value)
- select/status: eq, neq, gt, gte, lt, lte (by option title or sort order)
- record_reference: eq, neq (use {object_id, record_id} value)
- actor_reference: eq, neq (workspace member UUID)
- domain/email/phone/personal_name: eq, neq, contains, not-contains, starts-with, ends-with
example: {"and": [{"attribute": "is_customer", "op": "eq", "value": true}, {"attribute": "employee_count", "op": "gte", "value": 50}]}
offsetnumberNumber of entries to skip for pagination.default: 0
list-recordsList records in a given object with optional filtering and sorting. Returns paginated results. Use this tool to retrieve records that match specific criteria. You can filter on attributes using comparison operators, combine filters with AND/OR logic, and sort results by attrib...5 params
List records in a given object with optional filtering and sorting. Returns paginated results. Use this tool to retrieve records that match specific criteria. You can filter on attributes using comparison operators, combine filters with AND/OR logic, and sort results by attrib...
Parameters* required
limitnumberMaximum number of records to return (max 50).default: 10
sortsarraySorting to apply (max 2). If empty, results are returned in a deterministic random order. Sortable types: text, number, currency, date, timestamp, checkbox, rating, domain, email_address, phone_number, personal_name.
example: [{"attribute": "name", "direction": "asc"}]
filtervalueFilter criteria to apply. If null, returns all records. Filter syntax supports three types:
1. Single condition: {"attribute":"name", "op":"eq", "value":"Acme Corp"}
2. AND group (all must match): {"and": [{"attribute":"industry", "op":"eq", "value":"Technology"}, {"attribute":"employee_count", "op":"gte", "value":50}]}
3. OR group (any must match): {"or": [{"attribute":"stage", "op":"eq", "value":"Proposal"}, {"attribute":"stage", "op":"eq", "value":"Negotiation"}]}
Groups can be nested. Available operators by type:
- text: eq, neq, contains, not-contains, starts-with, ends-with
- number/currency/rating: eq, neq, gt, gte, lt, lte
- date: eq, neq, gt, gte, lt, lte (YYYY-MM-DD format, e.g. "2024-03-15")
- timestamp: eq, neq, gt, gte, lt, lte (full ISO 8601 with timezone preferred, e.g. "2024-03-15T14:30:00Z". Bare dates default to midnight UTC)
- checkbox: eq, neq (boolean value)
- select/status: eq, neq, gt, gte, lt, lte (by option title or sort order)
- record_reference: eq, neq (use {object_id, record_id} value)
- actor_reference: eq, neq (workspace member UUID)
- domain/email/phone/personal_name: eq, neq, contains, not-contains, starts-with, ends-with
example: {"and": [{"attribute": "is_customer", "op": "eq", "value": true}, {"attribute": "employee_count", "op": "gte", "value": 50}]}
objectstringThe object to list records from.
format: slug or UUID
example: "companies", "people", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
offsetnumberNumber of records to skip for pagination.default: 0
list-tasksLists tasks in the workspace with optional filters. Returns paginated results with task content, completion status, assignees, linked records, and deadlines. Use to find tasks by assignee, completion status, linked record, or date ranges.12 params
Lists tasks in the workspace with optional filters. Returns paginated results with task content, completion status, assignees, linked records, and deadlines. Use to find tasks by assignee, completion status, linked record, or date ranges.
Parameters* required
limitnumberMaximum number of results to return.default: 10
offsetnumberNumber of results to skip for pagination.default: 0
sort_bystringAttribute to sort results by. Defaults to deadline_at.one of
created_at · deadline_atdefault: deadline_atis_completedbooleanFilter by completion status. true returns only completed tasks, false returns only incomplete tasks. Omit to return all tasks.
created_at_gtestringFilter to tasks created at or after this timestamp (inclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
created_at_ltestringFilter to tasks created at or before this timestamp (inclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
sort_directionstringThe sort direction.one of
asc · descdefault: ascdeadline_at_gtestringFilter to tasks with deadline at or after this timestamp (inclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
deadline_at_ltestringFilter to tasks with deadline at or before this timestamp (inclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
linked_record_idstringFilter to tasks linked to a specific record. The record ID. Must be provided with linked_record_object.
example: 987f40c7-b789-4569-afea-e4dc42c139da
linked_record_objectstringFilter to tasks linked to a specific record. The object the linked record belongs to. Must be provided with linked_record_id.
format: slug or UUID
example: "people", "companies", "7bfd5133-7c2f-4a26-89d3-a84cd47734e0"
assignee_workspace_member_idvalueFilter by assignee. Pass a workspace member ID to find tasks assigned to that member. Pass null to find unassigned tasks. Omit to return tasks regardless of assignee.
example: b3fb52e7-4cec-4539-8128-697ddc0ce245
list-workspace-membersList members in the Attio workspace. Returns a list of matching members with their ID, email address, name, access level, and team memberships. Use the query parameter to filter by name, email, or team.2 params
List members in the Attio workspace. Returns a list of matching members with their ID, email address, name, access level, and team memberships. Use the query parameter to filter by name, email, or team.
Parameters* required
querystringFilter returned members using fuzzy search against member name, email address, and teams they are a member of. If null or not provided, returns all members.
example: "John Smith"
include_suspendedbooleanIf true, response will include suspended members.default: false
list-workspace-teamsList teams in the workspace. Teams are groups of workspace members used primarily for permission management. Returns an array of teams, each with: workspace_team_id, name, description, is_archived, created_at, and members (array of {name, email}).1 params
List teams in the workspace. Teams are groups of workspace members used primarily for permission management. Returns an array of teams, each with: workspace_team_id, name, description, is_archived, created_at, and members (array of {name, email}).
Parameters* required
include_archivedbooleanIf true, the response will include archived teams.default: false
run-basic-reportRun an aggregate report on records in an object or entries in a list. Use this tool when you need totals, averages, minimums, maximums, or grouped breakdowns. How to use: 1. Pick a source object/list via slug or UUID. 2. Choose a metric: - {"type":"count"} for counting records...4 params
Run an aggregate report on records in an object or entries in a list. Use this tool when you need totals, averages, minimums, maximums, or grouped breakdowns. How to use: 1. Pick a source object/list via slug or UUID. 2. Choose a metric: - {"type":"count"} for counting records...
Parameters* required
filtervalueFilter criteria to apply on the source dataset. If null, returns all records/entries from the source.
Filters are applied before metric aggregation and grouping. Filter syntax supports three types:
1. Single condition: {"attribute":"name", "op":"eq", "value":"Acme Corp"}
2. AND group (all must match): {"and": [{"attribute":"industry", "op":"eq", "value":"Technology"}, {"attribute":"employee_count", "op":"gte", "value":50}]}
3. OR group (any must match): {"or": [{"attribute":"stage", "op":"eq", "value":"Proposal"}, {"attribute":"stage", "op":"eq", "value":"Negotiation"}]}
Groups can be nested. Available operators by type:
- text: eq, neq, contains, not-contains, starts-with, ends-with
- number/currency/rating: eq, neq, gt, gte, lt, lte
- date: eq, neq, gt, gte, lt, lte (YYYY-MM-DD format, e.g. "2024-03-15")
- timestamp: eq, neq, gt, gte, lt, lte (full ISO 8601 with timezone preferred, e.g. "2024-03-15T14:30:00Z". Bare dates default to midnight UTC)
- checkbox: eq, neq (boolean value)
- select/status: eq, neq, gt, gte, lt, lte (by option title or sort order)
- record_reference: eq, neq (use {object_id, record_id} value)
- actor_reference: eq, neq (workspace member UUID)
- domain/email/phone/personal_name: eq, neq, contains, not-contains, starts-with, ends-with
example: {"and": [{"attribute": "is_customer", "op": "eq", "value": true}, {"attribute": "employee_count", "op": "gte", "value": 50}]}
metricvalueThe metric to report on.
Supports two types of metrics:
"count": count records/entries (does not require attribute_path): {"type":"count"}
"attribute": aggregate a numeric attribute (number/currency) with sum/mean/min/max/count:
- {"type":"attribute","attribute_path":[["companies","employee_count"]],"aggregation":"sum"}
- {"type":"attribute","attribute_path":[["deals","value"]],"aggregation":"mean"}
Aggregation happens after filter and before grouping.
format: metric object
sourcestringThe source dataset for the report. Must be a list or object.
Use a list/object slug or UUID. The first segment in any metric attribute_path or group_by path must reference this same source.
Use list-lists to find lists and list-attribute-definitions to discover source attributes.
format: slug or UUID
example: "companies", "1e3b505f-5123-476e-9f72-9cd232d91c82", "top_customers"
group_byarrayOne or more values to group by (max 2).
If omitted, the response is a single number.
If one grouping is provided, response is an object keyed by that grouping value.
If two groupings are provided, response is a nested object keyed by primary then secondary grouping value.
For two groupings, group_by[0] is primary (outer key) and group_by[1] is secondary (inner key).
Examples:
- [{"path":[["companies","industry"]]}]
- [{"path":[["deals","stage"]]},{"path":[["deals","owner"]]}]
format: Array of group by objects
search-call-recordings-by-metadataSearches all call recordings across the workspace by their metadata. Useful for finding call recordings based on who was on the call (workspace members or person records), related records (e.g., companies or deals), meeting title, and time range. Returns paginated results orde...9 params
Searches all call recordings across the workspace by their metadata. Useful for finding call recordings based on who was on the call (workspace members or person records), related records (e.g., companies or deals), meeting title, and time range. Returns paginated results orde...
Parameters* required
limitnumberdefault: 20
offsetnumberdefault: 0
starts_afterstringFilter to call recordings that started on or after this timestamp (inclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
starts_beforestringFilter to call recordings that started on or before this timestamp (inclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
related_record_idsarrayFilter to call recordings associated with specific records (e.g., companies or deals). Must be provided with related_record_object.
example: ["27171aca-5c1b-4a4b-8b27-81c22ecbef5d"]
meeting_title_querystringSearch for call recordings by meeting title. Supports full-text search with query enhancement (synonyms, stemming) and substring matching for partial queries.
example: quarterly review
related_record_objectstringThe object type of the related records. Must be provided with related_record_ids.
format: slug or UUID
example: "companies", "811c4b3f-3ae1-430d-be8f-50ed52109d5c"
speaker_person_record_idsarrayFilter to call recordings where specific person records were speakers. All specified persons must be present on the call.
example: ["dec6f1cc-1b11-449b-ad55-012aad6fb830"]
speaker_workspace_member_idsarrayFilter to call recordings where specific workspace members were speakers. All specified members must be present on the call.
example: ["15fb44ef-ee36-4d6a-acce-bebd37598bf5"]
search-emails-by-metadataSearches emails visible to the user by their metadata. Useful for finding emails based on participants, domain, and time range. Returns paginated results ordered by sent time (most recent first). Uses limit/offset pagination. When both domain and participant_email_addresses ar...6 params
Searches emails visible to the user by their metadata. Useful for finding emails based on participants, domain, and time range. Returns paginated results ordered by sent time (most recent first). Uses limit/offset pagination. When both domain and participant_email_addresses ar...
Parameters* required
limitnumberMaximum number of results to return.
example: 10default: 20
domainstringFilter by domain the email came from or was sent to. ORed with participant_email_addresses filter if both are provided.
example: example.com
offsetnumberNumber of results to skip for pagination.default: 0
sent_at_gtstringFilter to emails sent after this timestamp.
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-01T00:00:00.000Z
sent_at_ltstringFilter to emails sent before this timestamp.
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-31T23:59:59.999Z
participant_email_addressesarrayFilter by email participants. Filters by participants of all roles (from, to, cc, bcc). ORed with domain filter if both are provided.
format: Array of valid email addresses.
example: ["john@example.com", "jane@example.com"]
search-meetingsSearch across past and future meetings in the workspace. Returns paginated results with meeting metadata and associated call recording IDs. Useful for finding meetings based on participants, related records, and time range. Results are split into past_meetings (sorted by start...10 params
Search across past and future meetings in the workspace. Returns paginated results with meeting metadata and associated call recording IDs. Useful for finding meetings based on participants, related records, and time range. Results are split into past_meetings (sorted by start...
Parameters* required
limitnumberdefault: 20
offsetnumberdefault: 0
timezonestringIANA timezone string for all-day meeting calculations. If an invalid timezone is provided, UTC will be used as a fallback.
example: "America/New_York", "Europe/London"
starts_afterstringFilter to meetings starting after this timestamp (exclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-01T00:00:00.000Z
starts_beforestringFilter to meetings starting before this timestamp (exclusive).
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-31T23:59:59.999Z
related_record_idsarrayFilter to meetings linked to specific records. Must be provided with related_record_object.
example: ["fcc72913-e72f-4971-8da8-c9b51a92f656"]
related_record_objectstringThe object type for related record filtering. Must be provided with related_record_ids.
format: slug or UUID
example: "companies", "deals", "98aa073e-f5cc-4262-8785-0194c1c3c5fb"
related_records_operatorstringAND = meeting must be linked to ALL specified records. OR = meeting must be linked to ANY of the specified records.
example: "AND"one of
AND · ORdefault: ANDparticipant_email_addressesarrayFilter to meetings where participants with matching email addresses are present. Uses normalized email addresses (case-insensitive).
example: ["alice@example.com", "bob@example.com"]
participant_email_addresses_operatorstringAND = all specified emails must be participants. OR = any of the specified emails is a participant. Only valid when participant_email_addresses is provided.
example: "OR"one of
AND · ORdefault: ORsearch-notes-by-metadataSearches for notes by their metadata. Useful for finding notes based on parent record, meeting, author (workspace member), and creation time. Returns paginated results ordered by creation date (most recent first). Uses limit/offset pagination.8 params
Searches for notes by their metadata. Useful for finding notes based on parent record, meeting, author (workspace member), and creation time. Returns paginated results ordered by creation date (most recent first). Uses limit/offset pagination.
Parameters* required
limitnumberdefault: 10
offsetnumberdefault: 0
meeting_idstringUse to filter to notes associated with a specific meeting.
example: d2e13173-1b77-48b3-ab1e-cf508f43c73e
created_at_gtstringUse to filter to notes created after a specific point in timestamp.
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
created_at_ltstringUse to filter to notes created before a specific point in timestamp.
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-01-20T00:00:00.000Z
parent_record_idstringUse to filter to notes attached to a specific record. Must be provided with parent_record_object.
example: "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
parent_record_objectstringUse to filter to notes attached to a specific record. Must be provided with parent_record_id.
format: slug or UUID
example: "companies", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
workspace_membership_idstringUse to filter to notes associated with a specific workspace member.
example: 31abd9d6-667f-4240-b995-717be5ad126e
search-recordsPerform a full-text search for records in a given object. Only searches indexed attributes: domains, email addresses, phone numbers, name/title, description, social handles, and location. Returns paginated results.4 params
Perform a full-text search for records in a given object. Only searches indexed attributes: domains, email addresses, phone numbers, name/title, description, social handles, and location. Returns paginated results.
Parameters* required
limitnumberMaximum number of results to return.default: 10
querystringCase-insensitive, full-text search query. Searches indexed attributes: domains, email addresses, phone numbers, name/title, description, social handles, and location.
example: "Acme Corp"
objectstringThe ID or slug of the object to search records in.
format: slug or UUID
example: "companies", "492c42ea-4def-4e51-9d1b-9ce24fc9e57f"
offsetnumberNumber of results to skip for pagination.default: 0
semantic-search-call-recordingsSearches all call recordings across the workspace using semantic similarity. Returns call recordings that are most semantically similar to the query, even if the exact keywords are not present in the transcript. Useful for finding calls where a specific topic was discussed. Se...1 params
Searches all call recordings across the workspace using semantic similarity. Returns call recordings that are most semantically similar to the query, even if the exact keywords are not present in the transcript. Useful for finding calls where a specific topic was discussed. Se...
Parameters* required
querystringThe search query to find semantically similar call recordings. Searches both transcript content and call recording overviews (title and summary) using vector embeddings, finding calls where similar topics were discussed even if the exact keywords are not present.
example: quarterly revenue discussion
semantic-search-emailsSearches emails visible to the user using semantic similarity. Returns up to 20 emails that are most semantically similar to the query, even if exact keywords are not present. Useful for finding emails where a specific topic was discussed. Returns email metadata only (ID, subj...2 params
Searches emails visible to the user using semantic similarity. Returns up to 20 emails that are most semantically similar to the query, even if exact keywords are not present. Useful for finding emails where a specific topic was discussed. Returns email metadata only (ID, subj...
Parameters* required
querystringThe search query for semantic/content-based search.
example: meeting notes from last quarter
include_emails_of_othersbooleanIf true, search through emails of other workspace members as well. If false, only search through the user's own mailbox.
example: falsedefault: false
semantic-search-notesSearches all notes across the workspace using semantic similarity. Returns up to 20 notes that are most semantically similar to the query, even if the exact keywords are not present in the note. Useful for finding notes where a specific topic was discussed. Returns note metada...1 params
Searches all notes across the workspace using semantic similarity. Returns up to 20 notes that are most semantically similar to the query, even if the exact keywords are not present in the note. Useful for finding notes where a specific topic was discussed. Returns note metada...
Parameters* required
querystringThe search query to find semantically similar notes. This searches the body content of notes using vector embeddings, finding notes where similar topics were discussed even if the exact keywords are not present.
example: quarterly revenue discussion
update-listUpdate a list's name or API slug3 params
Update a list's name or API slug
Parameters* required
liststringThe ID or slug of the list to update.
format: slug or UUID
example: "sales_pipeline", "1398efcd-9538-4b34-8f38-147a91b86af7"
namestringThe new human-readable name of the list.
example: "Enterprise Sales"
api_slugstringThe new API slug for the list. Must be formatted in snake_case.
example: "enterprise_sales"
update-recordUse this tool to update people, companies, and other records by `record_id`.4 params
Use this tool to update people, companies, and other records by `record_id`.
Parameters* required
objectstringThe object type for the target record.
format: slug or UUID
example: "people", "companies", "996a8100-7763-4af6-97d5-8ec221e3c8eb"
valuesobjectAn object mapping attribute slugs or IDs to values. Use `api_slug` or `attribute_id` from `list-attribute-definitions` as the key.
# VALUE FORMATS BY ATTRIBUTE TYPE:
* text: String - "name": "Acme Corp"
* number: Number - "employee_count": 100
* checkbox: Boolean - "is_active": true
* date: ISO 8601 date - "founded_date": "2024-01-15"
* timestamp: ISO 8601 datetime - "created_at": "2024-01-15T10:30:00Z"
* rating: Number 0-5 - "priority": 3
* email_address: String or array of strings (depends on is_multiselect) - "email_addresses": ["alice@example.com"]
* phone_number: String or array of strings (depends on is_multiselect) - "phone_numbers": ["+14155551234"]
* domain: String or array of strings (depends on is_multiselect) - "domains": ["example.com", "attio.com"]
* select: Option title or UUID - "industry": "Software"
* status: Status title or UUID - "stage": "In Progress"
* currency: Number (uses attribute's configured currency) - "deal_value": 10000
* location: Address string - "address": "1 Infinite Loop, Cupertino, CA, 95014, US"
Or object - {"line_1": "1 Infinite Loop", "locality": "Cupertino", "region": "CA", "postcode": "95014", "country_code": "US", "latitude": "37.331741", "longitude": "-122.030333"}
* personal_name: "Lastname, Firstname" format (note: last name comes FIRST) - "contact_name": "Doe, John"
Or object with ALL THREE required fields: [{"first_name": "John", "last_name": "Doe", "full_name": "John Doe"}]
* actor_reference: Workspace member by email or UUID - "owner": "user@example.com"
* interaction: NOT WRITABLE - this attribute type cannot be set via the API
# RECORD REFERENCES (linking to other records):
Record reference attributes link to records in other objects (e.g., linking a deal to a company).
Formats supported:
1. By record ID: {"target_object": "companies", "target_record_id": "<uuid>"}
2. By matching attribute (must contain exactly ONE matching value):
{"target_object": "people", "email_addresses": [{"email_address": "alice@example.com"}]}
The key (e.g. "email_addresses") is an attribute slug on the target object.
3. Simple format (only if attribute references a single object type):
- For people: pass an email address - "contact": "alice@example.com" (matches by email)
- For companies: pass a domain - "company": "acme.com" (matches by domain)
- Otherwise: pass a record UUID - "related_record": "<uuid>"
# ARRAYS VS SINGLE VALUES:
For attributes with is_multiselect=true, always provide an array.
For single-value attributes, you can use either format: "name": "value" or "name": ["value"]
example: {"actor_reference_by_id":"67be5dad-575b-495f-b9a7-57e663be9852","actor_reference_by_email":"user@example.com","checkbox":true,"currency":13.37,"date":"2012-12-12","domain":["example.com","sub.example.com"],"email_address":["hello@example.com"],"location_simple_format":"1 Infinite Loop, Cupertino, CA, 95014, US","location_object_format":{"line_1":"1 Infinite Loop","locality":"Cupertino","region":"CA","postcode":"95014","country_code":"US","latitude":"37.331741","longitude":"-122.030333"},"number":1337,"personal_name_simple_format":"Smith, John","personal_name_object_format":{"first_name":"John","last_name":"Smith","full_name":"John Owen Smith"},"rating":3,"rating_min":0,"rating_max":5,"record_reference_by_id":[{"target_object":"companies","target_record_id":"fea1460c-cba2-4aac-bccb-9d6fa1518e74"}],"record_reference_by_value":[{"target_object":"people","email_addresses":[{"email_address":"test@example.com"}]}],"select":"Select option 1","select_multiselect":["Select option 1","Select option 2"],"text":"Text value","timestamp":"2012-12-12T12:12:121Z","7bcef5b9-6254-41e5-8ec6-1fcb93c87574":"Example text value attribute referenced by ID","name":"Acme Corp","industry":"Software","employee_count":100,"primary_contact":"Doe, John","email_addresses":["contact@acme.com"],"associated_company":[{"target_object":"companies","target_record_id":"46cc9100-e0f0-4ca9-ac14-138cfe38de67"}]}
record_idstringA UUID of the record to update.
example: 9625b54b-ad8d-4e2d-bf24-fac5b2f8eec0
patch_multiselect_valuesbooleanIf `true`, values provided for multiselect attributes will be created and prepended to the list of values that already exist (if any). If `false`, values provied for multiselect attributes will be either created or deleted as necessary to match the list of supplied values. Defaults to `true`.default: true
update-taskUpdates an existing task in Attio. You can update the deadline, completion status, assignee, and linked record. To update the assignee, provide their workspace_member_id. To update the linked record, provide both the object type (e.g., "people", "companies") and the record_id...6 params
Updates an existing task in Attio. You can update the deadline, completion status, assignee, and linked record. To update the assignee, provide their workspace_member_id. To update the linked record, provide both the object type (e.g., "people", "companies") and the record_id...
Parameters* required
task_idstringThe ID of the task to update.
example: 492c42ea-4def-4e51-9d1b-9ce24fc9e57f
deadline_atstringThe deadline date for the task. Set to null to clear the deadline.
format: ISO 8601 timestamp string. UTC timezone.
example: 2026-02-15T00:00:00.000Z
is_completedbooleanWhether the task is completed.
example: true
linked_record_idstringThe record ID to link the task to. Must be provided with linked_record_object.
example: 492c42ea-4def-4e51-9d1b-9ce24fc9e57f
linked_record_objectstringThe object type for the linked record. Must be provided with linked_record_id.
format: slug or UUID
example: "people", "companies"
assignee_workspace_member_idstringThe workspace member ID to assign the task to. Only one assignee can be specified via MCP.
example: 31abd9d6-667f-4240-b995-717be5ad126e
upsert-recordUse this tool to create or update people, companies and other records. A matching attribute is used to search for existing records. If a record is found with the same value for the `matching_attribute`, that record will be updated. If no record with the same value for the `mat...4 params
Use this tool to create or update people, companies and other records. A matching attribute is used to search for existing records. If a record is found with the same value for the `matching_attribute`, that record will be updated. If no record with the same value for the `mat...
Parameters* required
objectstringThe object type for the target record.
format: slug or UUID
example: "people", "companies", "839d729c-e0b0-4b6f-86d9-d7d876b3df07"
valuesobjectAn object mapping attribute slugs or IDs to values. Use `api_slug` or `attribute_id` from `list-attribute-definitions` as the key.
# VALUE FORMATS BY ATTRIBUTE TYPE:
* text: String - "name": "Acme Corp"
* number: Number - "employee_count": 100
* checkbox: Boolean - "is_active": true
* date: ISO 8601 date - "founded_date": "2024-01-15"
* timestamp: ISO 8601 datetime - "created_at": "2024-01-15T10:30:00Z"
* rating: Number 0-5 - "priority": 3
* email_address: String or array of strings (depends on is_multiselect) - "email_addresses": ["alice@example.com"]
* phone_number: String or array of strings (depends on is_multiselect) - "phone_numbers": ["+14155551234"]
* domain: String or array of strings (depends on is_multiselect) - "domains": ["example.com", "attio.com"]
* select: Option title or UUID - "industry": "Software"
* status: Status title or UUID - "stage": "In Progress"
* currency: Number (uses attribute's configured currency) - "deal_value": 10000
* location: Address string - "address": "1 Infinite Loop, Cupertino, CA, 95014, US"
Or object - {"line_1": "1 Infinite Loop", "locality": "Cupertino", "region": "CA", "postcode": "95014", "country_code": "US", "latitude": "37.331741", "longitude": "-122.030333"}
* personal_name: "Lastname, Firstname" format (note: last name comes FIRST) - "contact_name": "Doe, John"
Or object with ALL THREE required fields: [{"first_name": "John", "last_name": "Doe", "full_name": "John Doe"}]
* actor_reference: Workspace member by email or UUID - "owner": "user@example.com"
* interaction: NOT WRITABLE - this attribute type cannot be set via the API
# RECORD REFERENCES (linking to other records):
Record reference attributes link to records in other objects (e.g., linking a deal to a company).
Formats supported:
1. By record ID: {"target_object": "companies", "target_record_id": "<uuid>"}
2. By matching attribute (must contain exactly ONE matching value):
{"target_object": "people", "email_addresses": [{"email_address": "alice@example.com"}]}
The key (e.g. "email_addresses") is an attribute slug on the target object.
3. Simple format (only if attribute references a single object type):
- For people: pass an email address - "contact": "alice@example.com" (matches by email)
- For companies: pass a domain - "company": "acme.com" (matches by domain)
- Otherwise: pass a record UUID - "related_record": "<uuid>"
# ARRAYS VS SINGLE VALUES:
For attributes with is_multiselect=true, always provide an array.
For single-value attributes, you can use either format: "name": "value" or "name": ["value"]
example: {"actor_reference_by_id":"67be5dad-575b-495f-b9a7-57e663be9852","actor_reference_by_email":"user@example.com","checkbox":true,"currency":13.37,"date":"2012-12-12","domain":["example.com","sub.example.com"],"email_address":["hello@example.com"],"location_simple_format":"1 Infinite Loop, Cupertino, CA, 95014, US","location_object_format":{"line_1":"1 Infinite Loop","locality":"Cupertino","region":"CA","postcode":"95014","country_code":"US","latitude":"37.331741","longitude":"-122.030333"},"number":1337,"personal_name_simple_format":"Smith, John","personal_name_object_format":{"first_name":"John","last_name":"Smith","full_name":"John Owen Smith"},"rating":3,"rating_min":0,"rating_max":5,"record_reference_by_id":[{"target_object":"companies","target_record_id":"fea1460c-cba2-4aac-bccb-9d6fa1518e74"}],"record_reference_by_value":[{"target_object":"people","email_addresses":[{"email_address":"test@example.com"}]}],"select":"Select option 1","select_multiselect":["Select option 1","Select option 2"],"text":"Text value","timestamp":"2012-12-12T12:12:121Z","7bcef5b9-6254-41e5-8ec6-1fcb93c87574":"Example text value attribute referenced by ID","name":"Acme Corp","industry":"Software","employee_count":100,"primary_contact":"Doe, John","email_addresses":["contact@acme.com"],"associated_company":[{"target_object":"companies","target_record_id":"46cc9100-e0f0-4ca9-ac14-138cfe38de67"}]}
matching_attributestringThe ID or slug of the attribute to use to check if a record already exists. The attribute must be unique. The value for `matching_attribute` MUST be provided in the `values` payload.
example: "email_addresses", "domains", "f99ca43f-543f-46cb-bd8f-97f5f29537c0"
patch_multiselect_valuesbooleanIf `true`, values provided for multiselect attributes will be created and prepended to the list of values that already exist (if any). If `false`, values provied for multiselect attributes will be either created or deleted as necessary to match the list of supplied values. Defaults to `true`.default: true
whoamiReturns information about the current user's identity and workspace membership, including their email, name, workspace member ID, access level, and workspace name.
Returns information about the current user's identity and workspace membership, including their email, name, workspace member ID, access level, and workspace name.
No parameter schema in public metadata yet.
Attio MCP Server
A comprehensive Model Context Protocol (MCP) server for Attio, providing complete CRM surface coverage. This server enables AI assistants like Claude and ChatGPT to interact directly with your entire Attio workspace through natural language—manage Deals, Tasks, Lists, People, Companies, Records, and Notes without falling back to raw API calls.
🎯 What is Attio MCP Server?
Transform your CRM workflows with AI-powered automation. Instead of clicking through multiple screens, simply ask Claude or ChatGPT to find prospects, update records, manage pipelines, and analyze your data using natural language commands.
🎉 v1.0.0 Milestone: Complete Attio CRM surface coverage with full ChatGPT Developer Mode integration.
"Find all AI companies with 50+ employees that we haven't contacted in 30 days and add them to our Q1 outreach list"
🚀 ChatGPT Developer Mode Integration
⚠️ Smithery Temporarily Unavailable: Smithery has changed their deployment model to require external hosting. We're working on Cloudflare Worker hosting for ChatGPT users. In the meantime, use Tier 4 (Cloudflare Worker) for ChatGPT/remote access.
ChatGPT Pro/Plus users can access the Attio toolset through natural language using a self-hosted Cloudflare Worker:
- 🔐 Built-in Approval Flows: MCP safety annotations auto-approve read operations, request approval for writes
- 🌐 OAuth Integration: Self-hosted OAuth via Cloudflare Worker deployment
- 💬 Natural Language CRM: Manage your entire Attio workspace through conversational AI
- 📖 Setup Guide: See ChatGPT Developer Mode docs and Cloudflare Worker Guide
✨ Core Features & Implementation Status
🎯 Universal Tools Architecture (19 Universal Operations)
Focused Tool Surface: Consolidated 40+ resource-specific tools into universal operations, then added scoped high-frequency write tools for safer company and deal updates.
- High Performance: 89.7% speed improvement with 227KB memory reduction (PR #483)
- Enterprise Quality: 97.15/100 production readiness score with zero breaking changes
- Clean Architecture: Complete production-test separation with mock factory pattern
- Scoped Tool Policy: Add scoped default tools only when the workflow is frequent, a generic write can mutate the wrong object class, and the scoped tool removes a model decision instead of merely renaming a universal call
📊 Feature Implementation Status
✅ Complete CRM Surface Coverage
- Companies: Search, Create, Update, Delete, Advanced Search, Relationship Search
- People: Search, Create, Update, Delete, Advanced Search, Relationship Search
- Deals: Full CRUD operations with intelligent field mapping and stage validation
- Tasks: Create, Update, Delete, Search with multi-assignee support
- Lists: Full CRUD operations, filtering, advanced filtering, entry management
- Notes: Create and list operations for all record types
- Records: Universal CRUD operations across all resource types
- Batch Operations: Create, Update, Delete with chunking and error handling
- Content Search: Universal search capabilities across notes, tasks, and lists
- Relationship Navigation: Bidirectional company↔person↔deal relationships
- Advanced Filtering: Sophisticated query capabilities with intelligent field mapping
📊 Company Management
- Universal Search: Find companies with
search_recordsandsearch_records_advanced - Scoped Writes: Create and update companies with
create_companyandupdate_company - Full CRUD: Create, read, update, and delete with universal record operations when a scoped tool is not available
- Relationship Discovery: Find companies through
search_records_by_relationship - Batch Operations: Process hundreds of companies with
batch_records - Detailed Information: Get contact, business, and social info with
get_record_info
👥 People Management
- Universal Contact Search: Find people by any criteria using universal search tools
- Relationship Tracking: Link people to companies with
search_records_by_relationship - Activity Timeline: Track interactions with
search_records_by_contentandsearch_records_by_timeframe - Advanced Filtering: Multi-attribute search with universal filtering
- Bulk Operations: Efficiently manage contacts with universal batch operations
📋 Lists & Pipeline Management (4 Tools + 8 Deprecated)
- Active Tools: 4 consolidated tools with auto-mode detection (Migration Guide)
filter-list-entries- Unified filtering with 4 modesmanage-list-entry- Unified entry management with 3 modesget-list-entries- Retrieve list entriesget-record-list-memberships- Find record's list memberships
- Deprecated (v2.0.0 removal): 8 legacy tools replaced by consolidated versions
- Pipeline Operations: Move deals through sales stages
- Smart Segmentation: Create and manage targeted contact lists
- Advanced Filtering: Complex multi-condition filtering with AND/OR logic
- Entry Management: Add, remove, and update list memberships
- Deal Tracking: Monitor opportunities and revenue pipeline
- Deal Defaults: Configurable default stage, owner, and currency for streamlined deal creation
- Scoped Deal Writes: Create and update deals with
create_dealandupdate_deal
✅ Task Management
- Universal Task Operations: Create, update, and manage tasks with universal tools
- Record Linking: Associate tasks with any record type using
resource_typeparameter - Progress Tracking: Monitor completion with universal search and filtering
- Team Coordination: Streamline follow-ups with consistent universal operations
🔧 Advanced Capabilities
- Batch Processing: Handle bulk operations with error tracking
- Enhanced Filtering: Text, numeric, date, boolean, and relationship filters with timeframe search (Issue #475)
- Data Export: JSON serialization for integrations
- Real-time Updates: Live data synchronization with Attio
🧠 Claude Skills
Supercharge Claude's Attio knowledge with pre-built skills that prevent common errors and teach best practices.
| Skill | Purpose | Setup |
|---|---|---|
| attio-mcp-usage | Error prevention + universal workflow patterns | Bundled - just use it |
| attio-workspace-schema | YOUR workspace's exact field names and options | npx attio-discover generate-skill --all --zip |
| attio-skill-generator | Create custom workflow skills (advanced) | Python + prompting |
Quick Start (solves "wrong field name" errors):
npx attio-discover generate-skill --all --zip
# Import ZIP into Claude Desktop: Settings > Skills > Install Skill
See Skills Documentation for complete setup and usage guides.
💬 Pre-Built Prompts (10 Prompts)
Intelligent shortcuts that help Claude work faster with your CRM data:
- Search & Find (5): people_search, company_search, deal_search, meeting_prep, pipeline_health
- Take Actions (4): log_activity, create_task, advance_deal, add_to_list with dry-run safety
- Research & Qualify (1): qualify_lead with automated web research and BANT/CHAMP frameworks
- Token-efficient: 300-700 tokens per prompt with consistent formatting
- Discoverable: Claude automatically suggests relevant prompts for your tasks
See Using Out-of-the-Box Prompts for detailed documentation and examples.
🎯 Using Out-of-the-Box Prompts
NEW: 10 pre-built MCP prompts for common Sales workflows. No setup required—just use them!
Available Prompts
| Prompt | Description | Key Arguments | Example |
|---|---|---|---|
people_search.v1 | Find people by title, company, territory | query, limit, format | Find AE in fintech, SF |
company_search.v1 | Query companies by domain, segment, plan | query, limit, format | Find SaaS companies >100 employees |
deal_search.v1 | Filter deals by owner, stage, value, close date | query, limit, format | Find deals >$50k closing Q1 |
log_activity.v1 | Log calls/meetings/emails to records | target, type, summary, dry_run | Log call with Nina at Acme |
create_task.v1 | Create tasks with natural language due dates | title, content, due_date, dry_run | Create task: Follow up tomorrow |
advance_deal.v1 | Move deal to target stage with next action | deal, target_stage, create_task, dry_run | Advance deal to "Proposal Sent" |
add_to_list.v1 | Add records to a List by name or ID | records, list, dry_run | Add 5 companies to Q1 Outreach |
qualify_lead.v1 | Research lead with web + BANT/CHAMP scoring | target, framework, limit_web, dry_run | Qualify Acme Corp with BANT |
meeting_prep.v1 | 360° prep: notes, tasks, deals, agenda | target, format, verbosity | Prep for meeting with Acme CEO |
pipeline_health.v1 | Weekly snapshot: created/won/slipped + risks | owner, timeframe, segment | Pipeline health for @me last 30d |
Quick Examples
# Search for prospects
"Use people_search.v1: Find Account Executives in San Francisco at fintech companies, limit 25"
# Log activity
"Use log_activity.v1: Log a call with Nina at Acme Corp, discussed Q1 pricing, create follow-up task"
# Qualify a lead (with web research)
"Use qualify_lead.v1: Qualify Acme Corp using BANT framework, dry run mode"
# Meeting prep
"Use meeting_prep.v1: Prepare for meeting with contact at Acme Corp"
Universal Arguments
All read prompts support:
format:table|json|ids(default:table)fields_preset:sales_short|full(default:sales_short)verbosity:brief|normal(default:brief)
All write prompts support:
dry_run:true|false(default:false) - Preview changes without executing
Token Awareness Features
Prompts include built-in token optimization:
- Budget Guards: Prompts stay within token limits (people_search <500, qualify_lead <400)
- Dev Metadata: Set
MCP_DEV_META=truefor token counts in responses - Telemetry: Set
PROMPT_TELEMETRY_ENABLED=truefor usage logging - Configurable Limits: Override with
MAX_PROMPT_TOKENSenvironment variable
For complete prompt documentation, see docs/prompts/v1-catalog.md.
⚠️ Known Limitations & Important Notes
Current Limitations
- Field Parameter Filtering: Tasks endpoint
/objects/tasks/attributeshas limitations, handled with fallback patterns - Pagination: Tasks pagination uses in-memory handling due to API constraints
API Compatibility
- Universal Tools: Primary interface (19 tools) - recommended for all new integrations
- Legacy Tools: Available via
DISABLE_UNIVERSAL_TOOLS=trueenvironment variable (deprecated) - Lists API: Fully functional with complete CRUD operations (contrary to some outdated documentation)
🤝 OpenAI MCP Compatibility
- Developer Mode Ready: Every tool now publishes MCP safety annotations (
readOnlyHint,destructiveHint) so OpenAI Developer Mode can auto-approve reads and request confirmation for writes. - Full Tool Access (Default): All 41 tools are exposed by default (26 universal/OpenAI + 12 list + 3 workspace member). Do NOT set
ATTIO_MCP_TOOL_MODEin Smithery configuration for full access. - Search-Only Mode: To restrict to read-only tools (
search,fetch,aaa-health-check), explicitly configureATTIO_MCP_TOOL_MODE: 'search'in Smithery dashboard when Developer Mode is unavailable. - Detailed Guide: See docs/chatgpt-developer-mode.md for environment variables, approval flows, and validation tips.
- User Documentation: See the ChatGPT Developer Mode docs for a complete walkthrough of approval flows and setup instructions.
Performance Considerations
- Batch Operations: Optimized with chunking, rate limiting, and error recovery
- Large Datasets: Automatic pagination and field filtering for optimal performance
- Rate Limiting: Built-in protection against API rate limits with exponential backoff
For detailed troubleshooting and solutions, see TROUBLESHOOTING.md and GitHub Issues.
🎯 Advanced Search Filters
Build powerful CRM queries with multi-criteria AND/OR filtering. See the Advanced Search Guide for complete examples and operator reference.
🚀 Installation
⚠️ IMPORTANT: Correct Package Name
The npm package name is
attio-mcp(notattio-mcp-server). The GitHub repository is namedattio-mcp-server, but the npm package was renamed toattio-mcpin June 2025. Installingattio-mcp-serverwill give you an outdated v0.0.2 release with only 4 legacy tools.
Client Compatibility
| Client | Local Install (Tier 1-2) | Cloudflare Worker (Tier 3) |
|---|---|---|
| Claude Desktop | ✅ Recommended | ✅ Full support |
| Claude Web | N/A | ✅ Full support |
| ChatGPT (Pro/Plus) | N/A | ✅ Recommended |
| Cursor IDE | ✅ Full support | ✅ Full support |
| Claude Code (CLI) | ✅ Recommended | Partial |
Choose your installation method:
- Most users: Use Tier 1 (Shell Installers) - one command, automatic setup
- Power users: Use Tier 2 (Manual) - full control over configuration
- ChatGPT/Teams/Enterprise: Use Tier 3 (Cloudflare Worker) - self-hosted, multi-user OAuth
Tier 1: Shell Installers
Best for: Developers who prefer local installations with automatic configuration.
One-command scripts that install attio-mcp and configure your client automatically.
Claude Desktop
curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-claude-desktop.sh | bash
Cursor IDE
curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-cursor.sh | bash
Claude Code (CLI)
curl -fsSL https://raw.githubusercontent.com/kesslerio/attio-mcp-server/main/scripts/install-claude-code.sh | bash
These scripts will:
- Install
attio-mcpnpm package globally (if needed) - Backup existing configuration files
- Prompt for your Attio API key
- Configure the MCP server for your client
- Print next steps and restart instructions
Tier 2: Manual Configuration
Best for: Power users who prefer full control or use unsupported clients.
Claude Desktop Manual Setup
Step 1: Install attio-mcp
npm install -g attio-mcp
Step 2: Find your config file
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Step 3: Add configuration
{
"mcpServers": {
"attio-mcp": {
"command": "attio-mcp",
"env": {
"ATTIO_API_KEY": "your_api_key_here"
}
}
}
}
Step 4: Restart Claude Desktop completely (quit and reopen)
Cursor IDE Manual Setup
Step 1: Install attio-mcp
npm install -g attio-mcp
Step 2: Edit config file
Location: ~/.cursor/mcp.json
{
"mcpServers": {
"attio-mcp": {
"command": "attio-mcp",
"env": {
"ATTIO_API_KEY": "your_api_key_here"
}
}
}
}
Step 3: Restart Cursor
Claude Code (CLI) Manual Setup
Option A: Using Claude CLI command (recommended)
echo '{"command":"attio-mcp","env":{"ATTIO_API_KEY":"your_key_here"}}' | claude mcp add-json attio-mcp --stdin -s user
Option B: Manual config edit
Edit ~/.claude/settings.json:
{
"mcpServers": {
"attio-mcp": {
"command": "attio-mcp",
"env": {
"ATTIO_API_KEY": "your_api_key_here"
}
}
}
}
Building from Source
For development or custom deployments:
git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build
Run directly:
ATTIO_API_KEY=your_key node dist/index.js
NPM Global Install
# Global installation for CLI usage
npm install -g attio-mcp
# Or local installation for project integration
npm install attio-mcp
Tier 3: Cloudflare Worker (Remote Deployment)
Best for: Teams needing centralized OAuth, multi-user access, mobile access, or running MCP without local installation.
Deploy your own Attio MCP server on Cloudflare Workers with full OAuth 2.1 support.
Mobile Access: With a remote MCP server, you can use Attio tools from:
- ChatGPT mobile app (iOS/Android)
- Claude mobile app (iOS/Android)
- Any browser on any device
Cloudflare Worker Features
| Feature | Cloudflare Worker |
|---|---|
| Setup complexity | Medium |
| OAuth built-in | ✅ |
| Mobile app access | ✅ |
| Multi-user access | ✅ |
| Custom domain | ✅ |
| Self-hosted | ✅ |
| Team deployments | ✅ Full |
| Cost | Free tier |
Quick Deploy
cd examples/cloudflare-mcp-server
npm install
wrangler kv:namespace create "TOKEN_STORE"
# Update wrangler.toml with the KV namespace ID
wrangler secret put ATTIO_CLIENT_ID
wrangler secret put ATTIO_CLIENT_SECRET
wrangler secret put TOKEN_ENCRYPTION_KEY
wrangler deploy
Client Configuration
After deployment, configure your client with your Worker URL:
- Claude.ai: Settings → Connectors → Add your Worker URL
- ChatGPT: Settings → Connectors → Developer Mode → Add Worker URL
See Cloudflare Worker Deployment Guide for:
- Complete OAuth 2.1 setup with Attio
- Token encryption configuration
- Production deployment checklist
- Troubleshooting guide
🆕 What's New in v1.4.0
Major Features
- 🎯 Workspace Schema Skill Generator (#983) - Auto-generate Claude Skills from your Attio workspace schema for error-free field names and options
- 🔍 Select-field Transformer (#1019) - Case-insensitive matching, partial matching, and UUID pass-through for select/status fields
- 🛠️ Attio Skill Generator Meta-skill (#1020) - Meta-skill for automatic workspace documentation
- 📚 Universal Usage Guide Skill (#1018) - Hand-crafted workflow patterns and error prevention
- ⚙️
get_record_attribute_optionstool (#975) - Get valid options for select/status fields with enhanced error messages - 📞 Phone validation (#951) - Built-in phone number validation support
- ⏱️ Configurable option fetch delay - Rate limiting control via
--option-fetch-delayflag
Major Enhancements
- 🏷️ MCP-compliant tool naming (#1039) - All tools now use
snake_case, verb-first naming (old names work via aliases until v2.0.0) - 🎨 Custom object display names (#1017) - Fetch display names directly from Attio API
- 📖 Split integration patterns (#1023) - Progressive discovery patterns by use case
- 💡 Enhanced attribute error messages (#975) - Levenshtein distance suggestions for typos
Critical Fixes
- 📝 Note content line breaks preserved (#1052)
- 👤 People search "Unnamed" display fixed (#1051)
- ✅ Select field persistence (#1045)
- 🔗 Record-reference auto-transformation (#997)
- 📊 Multi-select array auto-transformation (#992)
- 🛡️ Complex attribute validation (#991)
- ⚠️ Field persistence false warnings (#995)
- 📦 SDK dependency pinning (#1025)
- 💼 Deal stage/UTM validation (#1043)
- 📍 Location field auto-normalization (#987)
Internal Improvements
- Tool alias system refactoring (#1041) - Type-safe constants with pattern-based generation
- Strategy Pattern for CRUD error handlers (#1001)
- Consolidated metadata fetching (#984)
- UniversalUpdateService modularization (#984)
- Select transformation type rename (#1055) -
select_title_to_arrayfor clarity
🔄 Migration Guide
Upgrading from v1.3.x or earlier? Tool names have changed to follow MCP naming conventions.
Old names still work via backward-compatible aliases, but will be removed in v2.0.0 (Q1 2026).
Tool Name Changes
| Old Name (Deprecated) | New Name (MCP-compliant) | Notes |
|---|---|---|
records_search | search_records | Verb-first pattern |
records_get_details | get_record_details | Verb-first pattern |
records_get_attributes | get_record_attributes | Verb-first pattern |
records_discover_attributes | discover_record_attributes | Verb-first pattern |
records_search_advanced | search_records_advanced | Verb-first pattern |
records_search_by_relationship | search_records_by_relationship | Verb-first pattern |
records_search_by_content | search_records_by_content | Verb-first pattern |
records_search_by_timeframe | search_records_by_timeframe | Verb-first pattern |
records_batch | batch_records | Verb-first pattern |
search-records | search_records | snake_case format |
get-record-details | get_record_details | snake_case format |
create-record | create_record | snake_case format |
update-record | update_record | snake_case format |
delete-record | delete_record | snake_case format |
create-note | create_note | snake_case format |
list-notes | list_notes | snake_case format |
smithery-debug-config | smithery_debug_config | snake_case format |
Action Required: Update your integrations to use new tool names before Q1 2026. See MIGRATION-GUIDE.md for the complete migration table.
⚡ Quick Start
Prerequisites
- Node.js (v18 or higher)
- Attio API Key (Get one here) or OAuth access token
- Attio Workspace ID
🔐 Authentication Options
The server supports two authentication methods—both use the same Bearer token scheme:
| Method | Environment Variable | Best For |
|---|---|---|
| API Key (recommended) | ATTIO_API_KEY | Long-term integrations, personal use |
| OAuth Access Token | ATTIO_ACCESS_TOKEN | OAuth integrations, third-party apps |
Note: If both are set,
ATTIO_API_KEYtakes precedence.OAuth Users: For detailed setup including PKCE flow and token refresh, see OAuth Authentication Guide.
1. Set Environment Variables
# Option 1: API Key (recommended for most users)
export ATTIO_API_KEY="your_api_key_here"
# Option 2: OAuth Access Token (for OAuth integrations)
# export ATTIO_ACCESS_TOKEN="your_oauth_access_token_here"
export ATTIO_WORKSPACE_ID="your_workspace_id_here"
# Optional: Deal defaults configuration
export ATTIO_DEFAULT_DEAL_STAGE="Interested" # Default stage for new deals
export ATTIO_DEFAULT_DEAL_OWNER="user@company.com" # Default owner email address (see below)
export ATTIO_DEFAULT_CURRENCY="USD" # Default currency for deal values
2. Test the Installation
# Test the MCP server
attio-mcp --help
# Discover your Attio workspace attributes
attio-discover attributes
3. 🎯 CRITICAL: Configure Field Mappings
The MCP server uses field mapping files to translate between natural language and Attio's API field names. This configuration is essential for proper operation.
Quick Setup
# 1. Copy the sample configuration to create your user config
cp configs/runtime/mappings/sample.json configs/runtime/mappings/user.json
# 2. Edit user.json to match your workspace's custom fields
# Focus on the "objects.companies" and "objects.people" sections
Configuration Files (in configs/runtime/mappings/)
default.json- Standard Attio CRM fields (loaded first, don't edit)sample.json- Examples with custom field templates (copy from this, not used at runtime)user.json- YOUR workspace-specific overrides (merged on top of default.json)
💡 Key Insight:
user.jsonis merged on top ofdefault.json, so only include overrides and additions. Don't duplicate mappings that already exist indefault.json.
How Configuration Merging Works
The MCP server loads configuration in this order:
default.json- Contains all standard Attio fields (Name, Description, Team, etc.)user.json- Your custom additions/overrides are merged on top
Example: If default.json has "Name": "name" and your user.json also has "Name": "name", that's wasted tokens. Only include fields that are:
- New custom fields (not in default.json)
- Different mappings (overriding default behavior)
Optimized user.json Example
{
"mappings": {
"attributes": {
"objects": {
"companies": {
"// Only your custom fields - defaults are inherited": "",
"Lead Score": "lead_score",
"B2B Segment": "b2b_segment",
"Industry Vertical": "custom_industry_field"
}
}
},
"lists": {
"// Only your specific lists": "",
"Sales Pipeline": "your-pipeline-list-id"
}
}
}
✅ Good: Only custom/override fields
❌ Wasteful: Duplicating standard fields from default.json
⚠️ Without proper mapping configuration, the MCP server may not work correctly with your custom fields and lists.
Next: Verify your field mappings work by testing with Claude:
"Find companies in our pipeline with lead score > 80"
4. Configure Claude Desktop
Add to your Claude Desktop MCP configuration:
Finding Required IDs
Deal Owner Email (for deal owner defaults):
The ATTIO_DEFAULT_DEAL_OWNER should be set to the email address of the workspace member who should own new deals by default. This is typically your own email address or the email address of your sales team lead.
# Example:
export ATTIO_DEFAULT_DEAL_OWNER="john.smith@company.com"
Note: The system will automatically resolve email addresses to workspace member references when creating deals.
Deal Stages:
Deal stages are specific to your workspace. Check your Attio workspace settings or use the discover-attributes command to find available stages for deals.
{
"mcpServers": {
"attio-mcp": {
"command": "attio-mcp",
"env": {
"ATTIO_API_KEY": "your_api_key_here",
"ATTIO_WORKSPACE_ID": "your_workspace_id_here",
"ATTIO_DEFAULT_DEAL_STAGE": "Interested",
"ATTIO_DEFAULT_DEAL_OWNER": "user@company.com",
"ATTIO_DEFAULT_CURRENCY": "USD"
}
}
}
}
🌟 Example Use Cases
For Sales Teams
"Find all companies in the AI space with 50+ employees that we haven't contacted in 30 days"
"Show me all prospects added yesterday"
"Find companies created in the last 7 days with revenue over $10M"
"Create a task to follow up with Microsoft about the enterprise deal"
"Add John Smith from Google to our Q1 prospect list"
For Marketing Teams
"Create a list of all SaaS companies who opened our last 3 emails but haven't responded"
"Show me engagement metrics for our outbound campaign this month"
"Add all attendees from the conference to our nurture sequence"
For Customer Success
"Show me all enterprise customers with upcoming renewal dates in Q1"
"Create tasks for check-ins with accounts that haven't been contacted in 60 days"
"Find all customers who mentioned pricing concerns in recent notes"
For Data Operations
"Update all companies with missing industry data based on their domains"
"Export all contacts added this quarter to CSV"
"Merge duplicate company records for Acme Corporation"
🔐 Security & Privacy
- Secure API Authentication: Industry-standard API key authentication
- No Data Storage: Direct API passthrough with no local data retention
- Open Source: Full transparency with Apache 2.0 license
- Optional On-Premises: Deploy in your own infrastructure
- npm Provenance: Published with Sigstore provenance — every release is cryptographically linked to the GitHub Actions build and source commit
Supply Chain Verification
This package is published with npm provenance, creating a verifiable chain from source code to published artifact. Verify a release:
# Check provenance attestation on any published version
npm view attio-mcp --json | jq .attestations
# With pnpm (v10+), enforce trust policy at install time
# pnpm trustPolicy: no-downgrade blocks packages published with weaker credentials
For maximum supply chain protection, install with pnpm v10+ which enforces:
trustPolicy: no-downgrade— blocks versions published with weaker credentials than prior versionsminimumReleaseAge— cooldown period before new versions can be installed
📚 Documentation
Comprehensive documentation is available in the docs directory:
Universal Tools (Recommended)
⚠️ Note: Universal tools documentation is currently being updated to match the latest implementation. Use the API directly or check the source code for the most accurate interface definitions.
- API Overview - High-level API concepts and patterns
- Universal Tools Source - Current implementation reference
- Tool Schemas - Parameter definitions and validation
Getting Started
Configuration
- Warning Filter Configuration - Understanding cosmetic vs semantic mismatches, ESLint budgets, and suppression strategies
- Field Verification Configuration - Field persistence verification and validation settings
- Search Scoring Configuration - Environment variables for relevance scoring, caching, and operator validation
API Reference
📋 Implementation Status: These docs describe the Attio API endpoints. For MCP tool usage, refer to universal tools documentation above.
- API Overview - General Attio API concepts
- Companies API - Company record endpoints ✅ Fully Implemented via Universal Tools
- People API - Person record endpoints ✅ Fully Implemented via Universal Tools
- Lists API - List management endpoints ✅ Fully Implemented
- Notes API - Notes endpoints ✅ Basic Implementation
- Tasks API - Task endpoints ✅ Implemented via Universal Tools
Advanced Topics
- Batch Operations - Bulk operations ✅ Implemented with chunking
- Advanced Filtering - Complex queries ✅ Implemented
- Error Handling - Error patterns ✅ Enhanced error handling
- Extending MCP - Customization guide
Deployment
🛠 Development
Setup Development Environment
git clone https://github.com/kesslerio/attio-mcp-server.git
cd attio-mcp-server
npm install
npm run build
npm run test:offline
Smithery CLI Development
For local development and testing with Smithery Playground:
npm run dev # Opens Smithery Playground with local server
See docs/deployment/smithery-cli-setup.md for detailed Smithery CLI development setup.
Testing
npm test # Run all tests
npm run test:offline # Run only offline tests (no API required)
npm run test:integration # Integration tests (requires ATTIO_API_KEY)
npm run e2e # E2E tests (requires ATTIO_API_KEY)
For E2E/integration tests, create .env with your ATTIO_API_KEY. See the Testing Guide for detailed setup.
Available Scripts
npm run build # Build TypeScript
npm run test # Run all tests
npm run test:offline # Run tests without API calls
npm run analyze:token-footprint # Generate baseline MCP token footprint report
npm run lint # Check code style
npm run check # Full quality check
npm run setup:test-data # Create test data for integration tests
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details on:
- Adding new tools and features
- Improving documentation
- Reporting bugs and requesting features
- Testing and quality assurance
📈 What's Next?
This initial release provides a solid foundation for CRM automation.
🔗 Links
- NPM Package: https://www.npmjs.com/package/attio-mcp
- GitHub Repository: https://github.com/kesslerio/attio-mcp-server
- Issues & Support: https://github.com/kesslerio/attio-mcp-server/issues
- Releases: https://github.com/kesslerio/attio-mcp-server/releases
- Attio Documentation: https://developers.attio.com/
📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Original Work Attribution: This project is based on initial work by @hmk under BSD-3-Clause license, with substantial modifications and enhancements by @kesslerio. The original BSD license notice is preserved in the LICENSE file as required.
Ready to transform your CRM workflow? Install Attio MCP Server today and experience the future of CRM automation with AI!
npm install -g attio-mcp
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
ATTIO_API_KEY*secretYour Attio API key (required for all tools except health-check)
ATTIO_WORKSPACE_IDOptional Attio workspace ID for workspace-specific operations
ATTIO_MCP_TOOL_MODETool mode: 'full' (all tools) or 'search' (search tools only). Default: 'full'
MCP_LOG_LEVELLogging level: 'DEBUG', 'INFO', 'WARN', 'ERROR'. Default: 'INFO'
Categories
Registryactive
Packageattio-mcp
TransportSTDIO
AuthRequired
UpdatedMay 14, 2026
