# Records and Data with NocoDB MCP
> Part of the NocoDB documentation (MCP Server). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL.
URL: https://nocodb.com/docs/mcp/records
Last updated: 2026-10-21
NocoDB MCP tools for records: query, aggregate, create, update and delete records, link them, add attachments and comments, import and export CSV.
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](/docs/mcp/connections#connection-tools-and-access). 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 |
## Related
* [Connections and access](/docs/mcp/connections)
* [NocoDB MCP Server overview](/docs/mcp)
---
## Related pages
- [NocoDB MCP Server](https://nocodb.com/docs/mcp.md): The NocoDB MCP server lets Claude, ChatGPT, Claude Code, Cursor and other AI assistants work with your NocoDB data through 200 tools, with OAuth or a token.
- [MCP Connections and Access](https://nocodb.com/docs/mcp/connections.md): Create a NocoDB MCP connection, choose the projects it can reach and the tools it can call, and authorize web clients such as Claude and ChatGPT with OAuth.
- [Tables and Fields with NocoDB MCP](https://nocodb.com/docs/mcp/schema.md): NocoDB MCP tools for structure: create and change tables, fields and select options, folders and duplicates, with a dry run before risky field changes.
- [Views with NocoDB MCP](https://nocodb.com/docs/mcp/views.md): NocoDB MCP tools for views: create and configure views, filters and sorts, share links, form field conditions, view folders, row coloring and date dependencies.
- [Workflows and Automation with NocoDB MCP](https://nocodb.com/docs/mcp/automation.md): NocoDB MCP tools for automation: build workflows step by step, test steps without running them, publish, and manage webhooks, scripts and automation folders.
- [Classic Apps, Dashboards and Docs with NocoDB MCP](https://nocodb.com/docs/mcp/apps-and-docs.md): NocoDB MCP tools for classic apps (interfaces), dashboards and widgets, and documents: create, configure, publish and share them through an AI assistant.
- [Members and Permissions with NocoDB MCP](https://nocodb.com/docs/mcp/permissions.md): NocoDB MCP tools for access: project and workspace members and teams, table and field permissions, row-level security policies and the audit log.
- [NocoDB Skills](https://nocodb.com/docs/mcp/skills.md): Use the NocoDB skill for Claude to list, create, update and delete NocoDB tables, fields, views and records through natural language with an API token.