recordcrm

recordcrm

recordcrm is a small client for the Attio CRM: it searches records with free-text or structured filters, creates records in any object, reads a single record or an attribute's definition and options, creates and updates company and deal records, lists workspace lists and their entries, and looks up workspace members — all through the Attio API v2.

This package is a clean-room rebuild, and a labelled core subset: it covers 12 of the 19 universal operations plus scoped writes documented for the original Attio MCP server. The omitted operations are listed under "Scope" below.

How it talks to the service

Every tool needs an Attio API token:

export ATTIO_API_KEY="your token"
# ATTIO_ACCESS_TOKEN is accepted as a fallback when ATTIO_API_KEY is unset.
# Optional override (default: https://api.attio.com/v2)
export ATTIO_API_URL="https://api.attio.com/v2"

With no token set, every call fails with an error naming ATTIO_API_KEY, before any request is made.

Wire-format note: the original project's README documents the tools and their purposes; the endpoint shapes here follow the public Attio API v2 and are documented reconstructions. Records live under /v2/objects/{object}/records; record search posts to the records query endpoint (.../records/query) with a full_text query clause when a query is given, or a filter object for advanced search; writes wrap attribute values as { "data": { "values": ... } }; attribute options are read from the attribute definition at /v2/objects/{object}/attributes/{attribute}. Responses are parsed as JSON (an empty success body reads as { "status": "ok" }), and an upstream HTTP error is reported with its status and body text.

Install

npx @reneturcios/recordcrm records_search '{"object":"companies","query":"acme"}'

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/recordcrm

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

The CLI mirrors the tools: one subcommand per tool, taking its arguments as a single JSON object.

recordcrm records_search '{"object":"companies","query":"acme","limit":5}'
recordcrm records_search_advanced '{"object":"companies","filters":{"name":{"$contains":"acme"}}}'
recordcrm records_create '{"object":"people","data":{"name":[{"value":"Ada"}]}}'
recordcrm records_get_info '{"object":"people","record_id":"..."}'
recordcrm lists_list '{}'
recordcrm --version

Exit codes: 0 on success, 1 on an API or validation error (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/recordcrm mcp

MCP client configuration:

{
  "mcpServers": {
    "recordcrm": {
      "command": "npx",
      "args": ["-y", "@reneturcios/recordcrm", "mcp"],
      "env": { "ATTIO_API_KEY": "your token" }
    }
  }
}

Tools

Tool	Input	What it does
records_search	object (required), query, limit	Search records in an object by free-text query.
records_search_advanced	object (required), filters (required), limit	Search records in an object with structured filters.
records_create	object (required), data (required)	Create a record in an object from attribute values.
records_get_info	object (required), record_id (required)	Fetch one record by ID from an object.
records_get_attribute_options	object (required), attribute (required)	Get an attribute definition, including its select options.
companies_create	data (required)	Create a company record from attribute values.
companies_update	record_id (required), data (required)	Update a company record by ID.
deals_create	data (required)	Create a deal record from attribute values.
deals_update	record_id (required), data (required)	Update a deal record by ID.
lists_list	—	List all lists in the workspace.
list_entries_list	list (required), limit	List entries in a list.
workspace_members_get	workspace_member_id (required)	Fetch one workspace member by ID.

Scope

Omitted from this core subset: records_search_by_relationship, records_get_interactions, records_batch, the universal records_update / records_delete operations, lists_create, lists_update_configuration, list_entries_filter, list_entries_manage, records_get_list_memberships, diagnostics_get, and the universal notes/tasks operations. The original's field-mapping configuration is also not reproduced: this subset passes attribute values and filters through in Attio API shape directly. Search results, record contents, and list data are produced by the upstream Attio service; this package reproduces the tool surface and the request/response handling, not that service's data.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.