NocoDB MCP Tools Reference
All tools use the mcp__plugin_nocodb-ops_nocodb__ prefix (the server is declared in this plugin's .mcp.json). Every tool call goes through the NocoDB MCP server.
The Contract: Community vs Cloud / Licensed
| Edition |
What the MCP server offers |
| Community Edition |
The record tools only -- the original eleven: getBaseInfo, getTablesList, getTableSchema, queryRecords, getRecord, countRecords, aggregate, createRecords, updateRecords, deleteRecords, readAttachment. No listTools, no hidden tools. The connection is created per base. |
| Cloud / licensed self-hosted |
The same tools plus many more (about 200 in 2026.09). Read tools and record create/update/delete are listed directly; schema, view, automation, permission and interface write tools stay out of the tool list and are reached with listTools(category) then callTool(name, arguments). |
Rule of thumb: use the listed tools for everything in this plugin; when a capability seems missing, check listTools before concluding it is unsupported. If listTools is absent, errors, or does not name the tool, the instance does not offer it.
Start every session with whoami: it names the user and base the MCP credential is pinned to and which permissions it carries. Effective authority is the intersection of that grant and the user's role on each resource, so a 403 on a write usually means a read-only role, not a missing tool.
Discovery Tools
Use these first to understand what data is available.
| Tool |
Purpose |
Key Parameters |
whoami |
Who the credential acts as, which base it is pinned to, what it may do (Cloud / licensed) |
None |
getBaseInfo |
Base name, ID, and metadata |
None |
getTablesList |
List all tables you can access |
None |
getTableSchema |
Columns, types, and views for one table |
tableId |
getBaseSchema |
Every table with fields and views in one call (Cloud / licensed) |
None |
listFields, listViews, listFilters, listSorts |
Read-only structure lookups (Cloud / licensed) |
tableId / viewId |
Always start with getTablesList to get table IDs. You need a tableId for almost every other tool.
Read Tools
Retrieve data without changing anything.
| Tool |
Purpose |
Key Parameters |
queryRecords |
Search and list records with filters, sorting, and pagination |
tableId, filter (preferred) or where, fields, sort[{field, direction}], page, pageSize, viewId |
getRecord |
Fetch one specific record by its ID |
tableId, recordId, fields |
countRecords |
Count how many records match a filter |
tableId, filter or where, viewId |
groupByRecords |
Count records per distinct value of one field ("appointments per status") |
tableId, fieldId, filter or where, sort, limit, offset |
listLinkedRecords |
Page through the records linked to one row |
tableId, fieldId, recordId, limit, offset |
exportCsv |
CSV text of a table or view (capped by maxRows, default 1000, max 10000) |
tableId or viewId, maxRows, delimiter |
Write Tools
Create, change, or remove data. Every record-array tool takes at most 100 records per call -- a longer array is rejected outright (the whole call fails, nothing is truncated), so split larger writes into batches of 100 or fewer.
| Tool |
Purpose |
Key Parameters |
createRecords |
Add new records (up to 100 per call) |
tableId, records[{fields:{}}] |
updateRecords |
Change existing records (send only changed fields; up to 100 per call). A link field is replaced, not appended to -- pass the complete list, [] to clear |
tableId, records[{id, fields:{}}] |
deleteRecords |
Remove records (up to 100 per call) |
tableId, records[{id}] |
linkRecords / unlinkRecords |
Add or remove individual links without restating the set (up to 100 records, 100 links per record) |
tableId, fieldId, records[{id, links:[{id}]}] |
Record Tools Behind listTools (Cloud / licensed)
Call listTools with a category, read the argument schemas it returns, then run the tool with callTool:
mcp__plugin_nocodb-ops_nocodb__listTools category: "records"
-> upsertRecords, updateRecordsByCondition, linkRecordsByDisplayValue
mcp__plugin_nocodb-ops_nocodb__callTool name: "upsertRecords"
arguments: { tableId: "<tableId>",
fieldsToMergeOn: ["Email"],
records: [ { "fields": { "Email": "jane@example.com", "Status": "Active" } } ] }
| Category |
Tools |
Use for |
records |
upsertRecords |
Insert-or-update on a business key -- up to 100 records and 3 merge fields per call, each result says inserted or updated. Replaces "query, then create or update" |
|
updateRecordsByCondition |
Set the same field values on every record matching a condition -- not capped at 100, the condition is required, answers with a count only. Run countRecords with the same condition first |
|
linkRecordsByDisplayValue |
Link by what rows are called instead of by id; unmatched and ambiguous titles are reported back |
data-io |
exportExcel |
.xlsx download link, signed for 3 hours (hand a spreadsheet to a person) |
|
importCsv |
Load CSV text into an existing table (tableId) or a new one (tableName -- every field becomes SingleLineText) |
trash |
listTrash, restoreFromTrash, restoreRecords |
Undo a delete (see record-management) |
callTool validates arguments against the same schema listTools returned -- read the names there, do not guess.
Analytics Tools
Run calculations across your data.
| Tool |
Purpose |
Key Parameters |
aggregate |
Sum, count, average, min, max, median, std_dev, and more |
tableId, aggregations[{field, type}], filterGroups[{alias, filter or where}] -- both arrays are required |
aggregate does not group by a field: each filterGroups entry produces one result block keyed by its alias. For one overall number use filterGroups: [{ "alias": "All" }]. To count per distinct value use groupByRecords.
File Tools
| Tool |
Purpose |
Key Parameters |
readAttachment |
Read files attached to a record |
files[] (the attachment objects from getRecord / queryRecords) |
Filters: filter (preferred) and where (fallback)
queryRecords, countRecords, groupByRecords, updateRecordsByCondition and each aggregate.filterGroups[] entry accept the same two forms. Pass only one of the two.
Structured filter -- field names and values are quoted for you, so commas, parentheses and quotes in values are safe:
filter: { "field": "Status", "operator": "eq", "value": "Active" }
filter: { "group_operator": "AND",
"filters": [ { "field": "Status", "operator": "eq", "value": "Active" },
{ "field": "Priority", "operator": "in", "value": ["High", "Urgent"] } ] }
A group's group_operator is AND or OR; its members may be conditions or nested groups. Field titles are case-insensitive here.
String where -- (field,operator,value) joined with ~and, ~or, ~not:
where: "(Status,eq,Active)~and(Priority,in,High,Urgent)"
Field names in where are case-sensitive. See search-filter for the full operator list.
Operators:
| Category |
Operators |
| Comparison |
eq, neq, gt, lt, gte, lte |
| Range |
btw, nbtw -- Time and text fields only (see below) |
| Text |
like, nlike |
| List |
in, allof, anyof, nallof, nanyof |
| Empty checks |
blank, notblank, null, notnull, empty, notempty |
| Checkbox |
checked, notchecked |
| Date |
isWithin plus a sub_operator |
Two traps the server rejects:
Dates need a sub-operator. On Date / DateTime fields every comparison needs sub_operator -- exactDate with the value YYYY-MM-DD for a calendar date. A bare date is read as the sub-operator and fails with '2026-06-01' is not supported.
filter: { "field": "Due Date", "operator": "gte", "sub_operator": "exactDate", "value": "2026-06-01" }
where: "(Due Date,gte,exactDate,2026-06-01)"
btw / nbtw are rejected on Number, Decimal, Currency, Percent, Rating, Duration, Date / DateTime and Checkbox fields (Operation btw is not supported for type <T>). Express every range as two bounds:
where: "(Due Date,gte,exactDate,2026-01-01)~and(Due Date,lte,exactDate,2026-12-31)"
Common Patterns
Pattern 1 -- List with filter and sort
Find all active orders, newest first, showing only key fields:
Tool: mcp__plugin_nocodb-ops_nocodb__queryRecords
Params:
tableId: <orders_table_id>
filter: { "field": "Status", "operator": "eq", "value": "Active" }
fields: ["Order Number", "Customer", "Total", "Date"]
sort: [{ "field": "Date", "direction": "desc" }]
pageSize: 50
sort is an array of objects { "field": "<name>", "direction": "asc" | "desc" }, applied in array order (first entry = highest priority). A string such as "-Date" or ["-Date"] is rejected (Expected object, received string at sort[0]). The one exception is groupByRecords, whose sort is a single field title with an optional - prefix for descending.
Pattern 2 -- Create and verify
Add a new record, then confirm it was saved:
Step 1 - Tool: mcp__plugin_nocodb-ops_nocodb__createRecords
Params:
tableId: <contacts_table_id>
records: [{ "fields": { "Name": "Jane Smith", "Email": "jane@example.com" } }]
Step 2 - Tool: mcp__plugin_nocodb-ops_nocodb__queryRecords
Params:
tableId: <contacts_table_id>
filter: { "field": "Email", "operator": "eq", "value": "jane@example.com" }
Pattern 3 -- Aggregate report
Get total revenue and order count, split by status:
Tool: mcp__plugin_nocodb-ops_nocodb__aggregate
Params:
tableId: <orders_table_id>
aggregations: [
{ "field": "Total", "type": "sum" },
{ "field": "Id", "type": "count" }
]
filterGroups: [
{ "alias": "Active", "filter": { "field": "Status", "operator": "eq", "value": "Active" } },
{ "alias": "Completed", "filter": { "field": "Status", "operator": "eq", "value": "Completed" } }
]
The result is one block per alias: { "Active": { "Total": 1200, "Id": 7 }, "Completed": { ... } }. When a field carries two or more aggregations the keys become "<field>.<type>" (for example Total.sum).
Pattern 4 -- Count per value
How many records sit in each status?
Tool: mcp__plugin_nocodb-ops_nocodb__groupByRecords
Params:
tableId: <orders_table_id>
fieldId: <status_field_id> (from getTableSchema)
Best Practices
- Resolve table IDs first -- always call
getTablesList before operating on data. Never guess IDs.
- Check the schema -- call
getTableSchema to confirm exact field names and types before querying.
- Use pagination --
pageSize defaults to 50 and is capped at 200 (the deployment may cap it lower; the response reports the page_size actually applied). Use page for large datasets and stop when a page comes back shorter than page_size.
- Filter on the server -- apply
filter (or where) instead of fetching all records and filtering locally.
- Request only needed fields -- use
fields to limit returned data and keep responses fast.
- Bulk operations in batches of 100 -- prefer one 100-record call over 100 single calls, never more than 100. For changes by condition use
updateRecordsByCondition; for a long CSV use importCsv.
Error Handling
| Error |
Meaning |
What to Do |
| "Table not found" |
Wrong tableId |
Re-run getTablesList and use the correct ID |
"Field not found" / Column alias '<name>' not found |
Typo or wrong case in a where field name |
Run getTableSchema to see exact field names |
| "Invalid filter" |
Bad where syntax |
Check parentheses and operator spelling, or switch to the structured filter |
'<date>' is not supported |
Bare date in a date filter |
Add exactDate: (Field,gte,exactDate,2026-06-01) |
Operation btw is not supported for type <T> |
btw / nbtw on a numeric, date or checkbox field |
Use two bounds with gte and lte |
Expected object, received string at sort[0] |
sort was given as strings |
Send [{ "field": "<name>", "direction": "asc" | "desc" }] |
Input validation error on records |
More than 100 records in one write call |
Split into batches of 100 or fewer |
| "Record not found" |
Wrong recordId |
Query first to confirm the record exists |
| 401 / 403 |
Auth or permission issue |
See the setup and troubleshoot skills |
1---2name: mcp-patterns-103description: |4 NocoDB MCP tools reference for data work -- which tools the server lists, which sit behind listTools/callTool, the Community vs Cloud/licensed contract, and the exact parameter shapes (100-record batches, sort objects, filter vs where, date sub-operators). Use when:5 - "what NocoDB tools are available?"6 - "how do I query records?"7 - "show me NocoDB MCP parameters"8 - "which tool do I use for..."9 - "NocoDB tool reference"10 - "listTools / callTool"11metadata:12 source: https://skillmd.com/skills/agents-store/mcp-patterns-1013---1415# NocoDB MCP Tools Reference1617All tools use the `mcp__plugin_nocodb-ops_nocodb__` prefix (the server is declared in this plugin's `.mcp.json`). Every tool call goes through the NocoDB MCP server.1819## The Contract: Community vs Cloud / Licensed2021| Edition | What the MCP server offers |22|---------|----------------------------|23| **Community Edition** | The record tools only -- the original eleven: `getBaseInfo`, `getTablesList`, `getTableSchema`, `queryRecords`, `getRecord`, `countRecords`, `aggregate`, `createRecords`, `updateRecords`, `deleteRecords`, `readAttachment`. No `listTools`, no hidden tools. The connection is created per base. |24| **Cloud / licensed self-hosted** | The same tools plus many more (about 200 in 2026.09). Read tools and record create/update/delete are **listed directly**; schema, view, automation, permission and interface *write* tools stay out of the tool list and are reached with `listTools(category)` then `callTool(name, arguments)`. |2526Rule of thumb: use the listed tools for everything in this plugin; when a capability seems missing, check `listTools` before concluding it is unsupported. If `listTools` is absent, errors, or does not name the tool, the instance does not offer it.2728Start every session with `whoami`: it names the user and base the MCP credential is pinned to and which permissions it carries. Effective authority is the intersection of that grant and the user's role on each resource, so a 403 on a write usually means a read-only role, not a missing tool.2930## Discovery Tools3132Use these first to understand what data is available.3334| Tool | Purpose | Key Parameters |35|------|---------|---------------|36| `whoami` | Who the credential acts as, which base it is pinned to, what it may do (Cloud / licensed) | None |37| `getBaseInfo` | Base name, ID, and metadata | None |38| `getTablesList` | List all tables you can access | None |39| `getTableSchema` | Columns, types, and views for one table | `tableId` |40| `getBaseSchema` | Every table with fields and views in one call (Cloud / licensed) | None |41| `listFields`, `listViews`, `listFilters`, `listSorts` | Read-only structure lookups (Cloud / licensed) | `tableId` / `viewId` |4243**Always start with `getTablesList`** to get table IDs. You need a `tableId` for almost every other tool.4445## Read Tools4647Retrieve data without changing anything.4849| Tool | Purpose | Key Parameters |50|------|---------|---------------|51| `queryRecords` | Search and list records with filters, sorting, and pagination | `tableId`, `filter` (preferred) or `where`, `fields`, `sort[{field, direction}]`, `page`, `pageSize`, `viewId` |52| `getRecord` | Fetch one specific record by its ID | `tableId`, `recordId`, `fields` |53| `countRecords` | Count how many records match a filter | `tableId`, `filter` or `where`, `viewId` |54| `groupByRecords` | Count records per distinct value of one field ("appointments per status") | `tableId`, `fieldId`, `filter` or `where`, `sort`, `limit`, `offset` |55| `listLinkedRecords` | Page through the records linked to one row | `tableId`, `fieldId`, `recordId`, `limit`, `offset` |56| `exportCsv` | CSV text of a table or view (capped by `maxRows`, default 1000, max 10000) | `tableId` or `viewId`, `maxRows`, `delimiter` |5758## Write Tools5960Create, change, or remove data. **Every record-array tool takes at most 100 records per call** -- a longer array is rejected outright (the whole call fails, nothing is truncated), so split larger writes into batches of 100 or fewer.6162| Tool | Purpose | Key Parameters |63|------|---------|---------------|64| `createRecords` | Add new records (up to 100 per call) | `tableId`, `records[{fields:{}}]` |65| `updateRecords` | Change existing records (send only changed fields; up to 100 per call). A link field is **replaced**, not appended to -- pass the complete list, `[]` to clear | `tableId`, `records[{id, fields:{}}]` |66| `deleteRecords` | Remove records (up to 100 per call) | `tableId`, `records[{id}]` |67| `linkRecords` / `unlinkRecords` | Add or remove individual links without restating the set (up to 100 records, 100 links per record) | `tableId`, `fieldId`, `records[{id, links:[{id}]}]` |6869## Record Tools Behind `listTools` (Cloud / licensed)7071Call `listTools` with a category, read the argument schemas it returns, then run the tool with `callTool`:7273```74mcp__plugin_nocodb-ops_nocodb__listTools category: "records"75 -> upsertRecords, updateRecordsByCondition, linkRecordsByDisplayValue7677mcp__plugin_nocodb-ops_nocodb__callTool name: "upsertRecords"78 arguments: { tableId: "<tableId>",79 fieldsToMergeOn: ["Email"],80 records: [ { "fields": { "Email": "jane@example.com", "Status": "Active" } } ] }81```8283| Category | Tools | Use for |84|----------|-------|---------|85| `records` | `upsertRecords` | Insert-or-update on a business key -- up to 100 records and 3 merge fields per call, each result says `inserted` or `updated`. Replaces "query, then create or update" |86| | `updateRecordsByCondition` | Set the same field values on **every** record matching a condition -- **not** capped at 100, the condition is required, answers with a count only. Run `countRecords` with the same condition first |87| | `linkRecordsByDisplayValue` | Link by what rows are called instead of by id; unmatched and ambiguous titles are reported back |88| `data-io` | `exportExcel` | `.xlsx` download link, signed for 3 hours (hand a spreadsheet to a person) |89| | `importCsv` | Load CSV text into an existing table (`tableId`) or a new one (`tableName` -- every field becomes `SingleLineText`) |90| `trash` | `listTrash`, `restoreFromTrash`, `restoreRecords` | Undo a delete (see **record-management**) |9192`callTool` validates `arguments` against the same schema `listTools` returned -- read the names there, do not guess.9394## Analytics Tools9596Run calculations across your data.9798| Tool | Purpose | Key Parameters |99|------|---------|---------------|100| `aggregate` | Sum, count, average, min, max, median, std_dev, and more | `tableId`, `aggregations[{field, type}]`, `filterGroups[{alias, filter or where}]` -- **both arrays are required** |101102`aggregate` does not group by a field: each `filterGroups` entry produces one result block keyed by its `alias`. For one overall number use `filterGroups: [{ "alias": "All" }]`. To count per distinct value use `groupByRecords`.103104## File Tools105106| Tool | Purpose | Key Parameters |107|------|---------|---------------|108| `readAttachment` | Read files attached to a record | `files[]` (the attachment objects from `getRecord` / `queryRecords`) |109110---111112## Filters: `filter` (preferred) and `where` (fallback)113114`queryRecords`, `countRecords`, `groupByRecords`, `updateRecordsByCondition` and each `aggregate.filterGroups[]` entry accept the same two forms. **Pass only one of the two.**115116**Structured `filter`** -- field names and values are quoted for you, so commas, parentheses and quotes in values are safe:117118```119filter: { "field": "Status", "operator": "eq", "value": "Active" }120121filter: { "group_operator": "AND",122 "filters": [ { "field": "Status", "operator": "eq", "value": "Active" },123 { "field": "Priority", "operator": "in", "value": ["High", "Urgent"] } ] }124```125126A group's `group_operator` is `AND` or `OR`; its members may be conditions or nested groups. Field titles are case-insensitive here.127128**String `where`** -- `(field,operator,value)` joined with `~and`, `~or`, `~not`:129130```131where: "(Status,eq,Active)~and(Priority,in,High,Urgent)"132```133134Field names in `where` are **case-sensitive**. See **search-filter** for the full operator list.135136**Operators:**137138| Category | Operators |139|----------|----------|140| Comparison | `eq`, `neq`, `gt`, `lt`, `gte`, `lte` |141| Range | `btw`, `nbtw` -- **Time and text fields only** (see below) |142| Text | `like`, `nlike` |143| List | `in`, `allof`, `anyof`, `nallof`, `nanyof` |144| Empty checks | `blank`, `notblank`, `null`, `notnull`, `empty`, `notempty` |145| Checkbox | `checked`, `notchecked` |146| Date | `isWithin` plus a `sub_operator` |147148**Two traps the server rejects:**1491501. **Dates need a sub-operator.** On Date / DateTime fields every comparison needs `sub_operator` -- `exactDate` with the value `YYYY-MM-DD` for a calendar date. A bare date is read as the sub-operator and fails with `'2026-06-01' is not supported`.151152 ```153 filter: { "field": "Due Date", "operator": "gte", "sub_operator": "exactDate", "value": "2026-06-01" }154 where: "(Due Date,gte,exactDate,2026-06-01)"155 ```1561572. **`btw` / `nbtw` are rejected** on Number, Decimal, Currency, Percent, Rating, Duration, Date / DateTime and Checkbox fields (`Operation btw is not supported for type <T>`). Express every range as two bounds:158159 ```160 where: "(Due Date,gte,exactDate,2026-01-01)~and(Due Date,lte,exactDate,2026-12-31)"161 ```162163---164165## Common Patterns166167### Pattern 1 -- List with filter and sort168169Find all active orders, newest first, showing only key fields:170171```172Tool: mcp__plugin_nocodb-ops_nocodb__queryRecords173Params:174 tableId: <orders_table_id>175 filter: { "field": "Status", "operator": "eq", "value": "Active" }176 fields: ["Order Number", "Customer", "Total", "Date"]177 sort: [{ "field": "Date", "direction": "desc" }]178 pageSize: 50179```180181`sort` is an **array of objects** `{ "field": "<name>", "direction": "asc" | "desc" }`, applied in array order (first entry = highest priority). A string such as `"-Date"` or `["-Date"]` is rejected (`Expected object, received string at sort[0]`). The one exception is `groupByRecords`, whose `sort` is a single field title with an optional `-` prefix for descending.182183### Pattern 2 -- Create and verify184185Add a new record, then confirm it was saved:186187```188Step 1 - Tool: mcp__plugin_nocodb-ops_nocodb__createRecords189Params:190 tableId: <contacts_table_id>191 records: [{ "fields": { "Name": "Jane Smith", "Email": "jane@example.com" } }]192193Step 2 - Tool: mcp__plugin_nocodb-ops_nocodb__queryRecords194Params:195 tableId: <contacts_table_id>196 filter: { "field": "Email", "operator": "eq", "value": "jane@example.com" }197```198199### Pattern 3 -- Aggregate report200201Get total revenue and order count, split by status:202203```204Tool: mcp__plugin_nocodb-ops_nocodb__aggregate205Params:206 tableId: <orders_table_id>207 aggregations: [208 { "field": "Total", "type": "sum" },209 { "field": "Id", "type": "count" }210 ]211 filterGroups: [212 { "alias": "Active", "filter": { "field": "Status", "operator": "eq", "value": "Active" } },213 { "alias": "Completed", "filter": { "field": "Status", "operator": "eq", "value": "Completed" } }214 ]215```216217The result is one block per alias: `{ "Active": { "Total": 1200, "Id": 7 }, "Completed": { ... } }`. When a field carries two or more aggregations the keys become `"<field>.<type>"` (for example `Total.sum`).218219### Pattern 4 -- Count per value220221How many records sit in each status?222223```224Tool: mcp__plugin_nocodb-ops_nocodb__groupByRecords225Params:226 tableId: <orders_table_id>227 fieldId: <status_field_id> (from getTableSchema)228```229230---231232## Best Practices2332341. **Resolve table IDs first** -- always call `getTablesList` before operating on data. Never guess IDs.2352. **Check the schema** -- call `getTableSchema` to confirm exact field names and types before querying.2363. **Use pagination** -- `pageSize` defaults to 50 and is capped at 200 (the deployment may cap it lower; the response reports the `page_size` actually applied). Use `page` for large datasets and stop when a page comes back shorter than `page_size`.2374. **Filter on the server** -- apply `filter` (or `where`) instead of fetching all records and filtering locally.2385. **Request only needed fields** -- use `fields` to limit returned data and keep responses fast.2396. **Bulk operations in batches of 100** -- prefer one 100-record call over 100 single calls, never more than 100. For changes by condition use `updateRecordsByCondition`; for a long CSV use `importCsv`.240241## Error Handling242243| Error | Meaning | What to Do |244|-------|---------|-----------|245| "Table not found" | Wrong `tableId` | Re-run `getTablesList` and use the correct ID |246| "Field not found" / `Column alias '<name>' not found` | Typo or wrong case in a `where` field name | Run `getTableSchema` to see exact field names |247| "Invalid filter" | Bad `where` syntax | Check parentheses and operator spelling, or switch to the structured `filter` |248| `'<date>' is not supported` | Bare date in a date filter | Add `exactDate`: `(Field,gte,exactDate,2026-06-01)` |249| `Operation btw is not supported for type <T>` | `btw` / `nbtw` on a numeric, date or checkbox field | Use two bounds with `gte` and `lte` |250| `Expected object, received string at sort[0]` | `sort` was given as strings | Send `[{ "field": "<name>", "direction": "asc" \| "desc" }]` |251| Input validation error on `records` | More than 100 records in one write call | Split into batches of 100 or fewer |252| "Record not found" | Wrong `recordId` | Query first to confirm the record exists |253| 401 / 403 | Auth or permission issue | See the **setup** and **troubleshoot** skills |