Records and Data with NocoDB MCP

An MCP client can read, change and analyze the records of your NocoDB projects. It can also link records, add attachments and comments, import and export data, restore records from the trash and use record templates.

These 37 tools are in the Records & data section of Tools & Permissions. A tool needs the access level in its row: Read, Read & write, or Read, write & delete.

How the assistant works with records

The record tools take a maximum of 100 records in each call.

The create and update tools also take returnFields, a list of field titles or ids. The response then carries only those fields for each record, which keeps a large write readable.

Updating a link field through the update tool replaces the whole set, so pass the complete list of linked records you want, or [] to clear it. null is not a link value and leaves the links untouched. The link and unlink tools add or remove individual links without restating the set.

Link records by their display value, not by record id. Upsert records that match on a maximum of three business-key fields, not on record id. Set the same field values on all records that match a condition, in one call and with no 100-record limit.

Linking by display value matches exactly and adds to the existing links. A value that matches no record, or that matches more than one, is reported back instead of being linked, so link by record id where titles repeat. Updating by condition requires a condition: there is no form of it that updates every record.

Upload files into an Attachment field from an http(s) or data: URL, with a maximum of 10 files in each call. The tool adds the files to the cell that you name, or returns them for you to write into a record.

List the items in the project trash. Restore one entry by its trash id. Restore deleted records by row id. Only tables on a NocoDB-managed source keep deleted rows.

Export a table or view to CSV or as an .xlsx workbook. Import CSV into a table. Exported Decimal and Currency values keep their stored precision, not the display setting of the field.

A CSV that an MCP client appends to an existing table can fill at most 5000 links, counting every value in every Links field cell. A CSV over that limit is refused before any row is written, so split it into smaller files and import them one after another.

List, post, resolve, and delete comments. List, read, create, update, and delete record templates. Create a record from a template, together with the records that the template links.

Tools

Records

Tool	What it does	Access level
`getBaseInfo` ¹	Fetch information about current project.	Read
`getTablesList` ¹	List tables accessible by user.	Read
`getTableSchema` ¹	Get the table schema including fields and views information.	Read
`queryRecords` ¹	Query Records from a Table.	Read
`getRecord` ¹	Fetch a record by ID.	Read
`countRecords` ¹	Count Records in a Table.	Read
`readAttachment` ¹	Read the content of attachment objects returned by getRecord or queryRecords from an Attachment field.	Read
`aggregate_single` ¹	Perform aggregations on a table with a filter condition.	Read
`aggregate`	Perform aggregations (sum, count, avg, etc.) on table data, optionally split across filter groups (each `filterGroups` entry produces its own result, keyed by its alias).	Read
`groupByRecords`	Count records per distinct value of a field: "appointments per status".	Read
`listLinkedRecords`	Page through the records linked to one row through a Link field.	Read
`createRecords` ¹	Create records in a table.	Read & write
`updateRecords` ¹	Update records in a table.	Read & write
`linkRecords` ¹	Add links from records in this table to records in the linked table through a link field.	Read & write
`unlinkRecords` ¹	Remove specific links from records in this table through a link field.	Read & write
`linkRecordsByDisplayValue`	Link records by what they are called rather than by id: pass the display values (titles) of the records on the linked table.	Read & write
`upsertRecords`	Insert records, updating the ones that already exist instead of duplicating them: matched on the fields named in fieldsToMergeOn rather than on record id, so an agent holding an external key does not have to query first.	Read & write
`updateRecordsByCondition`	Set the same field values on every record matching a condition: "set Status to Archived where Closed is before 2024".	Read & write
`deleteRecords` ¹	Delete records in a table.	Read, write & delete

Comments

Tool	What it does	Access level
`listComments`	List comments on a record.	Read
`createComment`	Add a comment to a record.	Read & write
`updateComment`	Update an existing comment.	Read & write
`resolveComment`	Resolve or reopen a comment.	Read & write
`deleteComment`	Delete a comment.	Read, write & delete

Attachments

Tool	What it does	Access level
`uploadAttachment`	Put a file into an Attachment field.	Read & write

Import and export

Tool	What it does	Access level
`exportCsv`	Export a table or view as CSV text, with the field order, visibility, filters and sorts of the view.	Read
`exportExcel`	Export a table or view as an .xlsx workbook and return a download link.	Read
`importCsv`	Load CSV text into the project: either as a new table, or as rows appended to an existing one.	Read & write

Trash

Tool	What it does	Access level
`listTrash`	What is in the project trash: deleted records, tables, views, fields, dashboards, scripts and the rest, newest first.	Read
`restoreFromTrash`	Put one trashed item back.	Read & write
`restoreRecords`	Put deleted records back into a table by row id: the inverse of deleteRecords, for rows still inside the retention window.	Read & write

Record templates

Tool	What it does	Access level
`listRecordTemplates`	List the saved record templates of a project, or of one table.	Read
`getRecordTemplate`	Read one record template in full, including the `template_data` payload it writes: `fields` (field title → value) and `linked_records` (link field id → records to link or create).	Read
`createRecordTemplate`	Save a starter record for a table.	Read & write
`updateRecordTemplate`	Update a record template.	Read & write
`createRecordFromTemplate`	Create a record from a saved template.	Read & write
`deleteRecordTemplate`	Delete a record template.	Read, write & delete

¹ Also in the Community Edition, which offers only the record tools. There, aggregate_single takes the place of aggregate.

All editions give the record tools. With the record tools, an MCP client can:

list tables and read their schema, with or without the system created and updated fields
query, count, and aggregate records
read attachments
create, update, and delete records
add or remove single links through a link field

Limits

	Limit
Records per create, update or delete call	100
Records per `queryRecords` page	50 by default, 200 at most
Records and links per `linkRecords` or `unlinkRecords` call	100 records, 100 links each
Linked records per `listLinkedRecords` page	25 by default, 100 at most
Rows per `exportCsv` call	1,000 by default, 10,000 at most
Files per attachment upload	10
Links filled by one CSV append	5,000

Example prompts

Action	Purpose	Sample Prompt
Create	Add new records	Create a task named 'Review Documentation'
Read	Look up information	Show me all projects with deadlines this week
Update	Change existing data	Mark the status of Project X as completed & re-assign to John
Delete	Remove records	Remove all tasks assigned to John
Link	Link or unlink related records	Link the onboarding tasks to the Acme project