Skip to content

Commit 6ec64ab

Browse files
ARHAEEMclaude
ARHAEEM
and
claude
committed
docs(mcp-server): Claude Quick Start + refresh for v2.2.0 tool additions
- Add five-step Claude Quick Start (prerequisites → doctor → install-browser → login → configure Claude Desktop/Code → try it) so users can go from zero to a working MCP without the VS Code extension. - Split Claude Desktop (claude_desktop_config.json per-OS paths) from Claude Code (claude mcp add --scope user|project). - Add troubleshooting table, Browser Choice env var, full env var list, and "All CLI commands" reference. - Bump tool count 30 → 36 and add Table Management section for create_table / rename_table / delete_table. - Add get_view to Schema Read; note is/isNot auto-normalization on update_view_filters; note url/email/phone/dateTime aliases on create_field; note compact dep summary on delete_field. - Mention delete_table in Safety. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent ce321c9 commit 6ec64ab

File tree

1 file changed

+178
-39
lines changed

1 file changed

+178
-39
lines changed

‎packages/mcp-server/README.md‎

Lines changed: 178 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
# airtable-user-mcp
66

7-
**Community MCP server for Airtable — 30 tools your AI assistant can't get from the official API**
7+
**Community MCP server for Airtable — 36 tools your AI assistant can't get from the official API**
88

99
<p align="center">
1010
<a href="https://www.npmjs.com/package/airtable-user-mcp"><img src="https://img.shields.io/npm/v/airtable-user-mcp?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=CB3837" alt="npm version" /></a>
@@ -54,7 +54,7 @@ The official Airtable REST API doesn't expose formula field creation, view confi
5454
npx airtable-user-mcp
5555
```
5656

57-
That's it. Your MCP client connects via **stdio** and gets access to all 30 tools.
57+
That's it. Your MCP client connects via **stdio** and gets access to all 36 tools.
5858

5959
---
6060

@@ -84,11 +84,63 @@ For a visual management experience, install the **[Airtable Formula](https://mar
8484

8585
---
8686

87-
## Installation
87+
## Claude Quick Start (no VS Code extension)
8888

89-
### Via npx (recommended)
89+
Five commands take you from zero → a working Airtable MCP in Claude Desktop or Claude Code. Everything below runs from a normal terminal.
90+
91+
### Prerequisites
92+
93+
- **Node.js 18 or newer** — `node -v` to check. Install from [nodejs.org](https://nodejs.org) if missing.
94+
- An Airtable account (personal, team, or enterprise — anything you can log into at [airtable.com](https://airtable.com)).
95+
96+
### 1. Check what's already on your machine
97+
98+
```bash
99+
npx -y airtable-user-mcp@latest doctor
100+
```
101+
102+
`doctor` prints your Node version, platform, config dir, and whether the browser engine is installed. If `Patchright: not installed` appears, continue to step 2. If it says `installed`, skip to step 3.
103+
104+
### 2. Install the browser engine (one-time, ~170 MB)
105+
106+
```bash
107+
npx -y airtable-user-mcp install-browser
108+
```
109+
110+
This downloads [Patchright](https://github.com/Kaliiiiiiiiii/patchright-nodejs) (a stealth Chromium fork used only for the login flow). You only need to run this once per machine. If you already have Chrome, Edge, or Chromium installed and prefer not to download another browser, see [Browser Choice](#browser-choice) below.
111+
112+
### 3. Log in to Airtable
113+
114+
```bash
115+
npx -y airtable-user-mcp login
116+
```
117+
118+
A browser window opens on [airtable.com/login](https://airtable.com/login). Sign in like you normally would — password, SSO, 2FA, whatever your account uses. The window closes automatically when login is detected. Your session is stored in `~/.airtable-user-mcp/.chrome-profile/` and reused by every tool call.
119+
120+
Verify the session landed:
121+
122+
```bash
123+
npx -y airtable-user-mcp status
124+
```
125+
126+
You should see `Session: found`.
127+
128+
### 4. Configure your Claude client
90129

91-
Add to your MCP client config (`mcp.json`, `claude_desktop_config.json`, etc.):
130+
<details open>
131+
<summary><strong>Claude Desktop</strong></summary>
132+
133+
Open `claude_desktop_config.json`:
134+
135+
| OS | Path |
136+
|:--|:--|
137+
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
138+
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
139+
| Linux | `~/.config/Claude/claude_desktop_config.json` |
140+
141+
Tip: in Claude Desktop, **Settings → Developer → Edit Config** opens this file.
142+
143+
Add the `airtable` entry to `mcpServers`:
92144

93145
```json
94146
{
@@ -101,9 +153,99 @@ Add to your MCP client config (`mcp.json`, `claude_desktop_config.json`, etc.):
101153
}
102154
```
103155

156+
Save, then **fully quit and reopen Claude Desktop** (closing the window is not enough). A hammer/plug icon in the chat input confirms the server is connected — click it to see the 36 tools.
157+
158+
</details>
159+
160+
<details open>
161+
<summary><strong>Claude Code</strong></summary>
162+
163+
Use the built-in `claude mcp add` command:
164+
165+
```bash
166+
# Add for all projects on this machine:
167+
claude mcp add airtable --scope user -- npx -y airtable-user-mcp
168+
169+
# OR — add to the current project only (creates .mcp.json, safe to commit):
170+
claude mcp add airtable --scope project -- npx -y airtable-user-mcp
171+
```
172+
173+
Verify:
174+
175+
```bash
176+
claude mcp list
177+
```
178+
179+
You should see `airtable: npx -y airtable-user-mcp - ✓ Connected`. Start a Claude Code session in that directory and the 36 tools are available.
180+
181+
</details>
182+
183+
### 5. Try it out
184+
185+
Ask your Claude client:
186+
187+
> *"List all tables in my Airtable base `appXXXXXXXXXXXXXX`."*
188+
189+
It will call `list_tables` and return the names and IDs.
190+
191+
---
192+
193+
### Troubleshooting
194+
195+
| Symptom | Fix |
196+
|:--|:--|
197+
| `Session: not found` | Re-run `npx -y airtable-user-mcp login` |
198+
| Login window never loads | Check network / firewall, then `doctor` |
199+
| Browser download fails on Windows | Run PowerShell as Admin once, then retry `install-browser` |
200+
| Tools don't appear after config change | Fully quit and reopen Claude Desktop (not just the window) |
201+
| `command not found: npx` | Install Node.js from [nodejs.org](https://nodejs.org) |
202+
203+
Run `npx -y airtable-user-mcp doctor` at any time for a full diagnostic.
204+
205+
### Browser Choice
206+
207+
If you already have Chrome, Edge, or a system Chromium and want to skip the 170 MB download:
208+
209+
```bash
210+
# point the server at an existing Chromium-family browser
211+
export AIRTABLE_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" # macOS
212+
# or on Windows (PowerShell):
213+
$env:AIRTABLE_BROWSER_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
214+
```
215+
216+
### Useful environment variables
217+
218+
| Variable | Purpose |
219+
|:--|:--|
220+
| `AIRTABLE_USER_MCP_HOME` | Override config dir (default: `~/.airtable-user-mcp`) |
221+
| `AIRTABLE_NO_BROWSER` | Skip Patchright entirely — uses cached cookies only (CI/headless) |
222+
| `AIRTABLE_HEADLESS_ONLY` | Run the browser without a visible window |
223+
| `AIRTABLE_LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` |
224+
225+
---
226+
227+
## Installation
228+
229+
### Via npx (recommended)
230+
231+
Already covered above — the `claude mcp add` command or the `mcpServers` JSON entry both use `npx -y airtable-user-mcp` under the hood.
232+
104233
### Via VS Code / Windsurf / Cursor
105234

106-
Install the [Airtable Formula](https://marketplace.visualstudio.com/items?itemName=Nskha.airtable-formula) extension — it bundles this server and registers it automatically across all your IDEs.
235+
Install the [Airtable Formula](https://marketplace.visualstudio.com/items?itemName=Nskha.airtable-formula) extension — it bundles this server and registers it automatically across all your IDEs. Login and status live in a visual dashboard.
236+
237+
### Global install
238+
239+
```bash
240+
npm install -g airtable-user-mcp
241+
airtable-user-mcp login
242+
```
243+
244+
Then reference the binary directly in any MCP config:
245+
246+
```json
247+
{ "mcpServers": { "airtable": { "command": "airtable-user-mcp" } } }
248+
```
107249

108250
### From source
109251

@@ -120,32 +262,24 @@ Install the [Airtable Formula](https://marketplace.visualstudio.com/items?itemNa
120262

121263
---
122264

123-
## Authentication
124-
125-
The server uses browser-based authentication via [Patchright](https://github.com/Kaliiiiiiiiii/patchright-nodejs).
126-
127-
```bash
128-
# 1. Install the browser engine (one-time, ~170 MB)
129-
npx airtable-user-mcp install-browser
130-
131-
# 2. Log in to Airtable
132-
npx airtable-user-mcp login
265+
## All CLI commands
133266

134-
# 3. Verify your session
135-
npx airtable-user-mcp status
136267
```
137-
138-
Sessions are cached in `~/.airtable-user-mcp/` and reused automatically.
139-
140-
**Headless / CI environments:** Set `AIRTABLE_NO_BROWSER=1` to use cached cookies only, without launching a browser.
141-
142-
**Diagnostics:** Run `npx airtable-user-mcp doctor` to check browser availability, session health, and config.
268+
npx airtable-user-mcp Start MCP server (stdio) ← what your Claude client runs
269+
npx airtable-user-mcp login Log in to Airtable via browser
270+
npx airtable-user-mcp logout Clear saved session
271+
npx airtable-user-mcp status Show session & browser info
272+
npx airtable-user-mcp doctor Run diagnostics
273+
npx airtable-user-mcp install-browser Download Chromium (~170 MB)
274+
npx airtable-user-mcp --version Print version
275+
npx airtable-user-mcp --help Show this help
276+
```
143277

144278
---
145279

146-
## Tools (30)
280+
## Tools (36)
147281

148-
### Schema Read (5)
282+
### Schema Read (7)
149283

150284
| Tool | Description |
151285
|:-----|:------------|
@@ -154,19 +288,29 @@ Sessions are cached in `~/.airtable-user-mcp/` and reused automatically.
154288
| `get_table_schema` | Full schema for a single table |
155289
| `list_fields` | All fields in a table with types and configuration |
156290
| `list_views` | All views in a table with IDs, names, and types |
291+
| `get_view` | Read a single view's full state — filters, sorts, grouping, visibility, description |
292+
| `validate_formula` | Validate a formula expression before applying |
293+
294+
### Table Management (3)
295+
296+
| Tool | Description |
297+
|:-----|:------------|
298+
| `create_table` | Create a new table with default fields |
299+
| `rename_table` | Rename a table |
300+
| `delete_table` | Delete a table (requires `expectedName` safety guard) |
157301

158302
### Field Management (8)
159303

160304
| Tool | Description |
161305
|:-----|:------------|
162-
| `create_field` | Create a field — including formula, rollup, lookup, count |
306+
| `create_field` | Create a field — auto-maps `url` / `email` / `phone` / `dateTime` aliases, plus formula, rollup, lookup, count |
163307
| `create_formula_field` | Create a formula field (shorthand) |
164-
| `validate_formula` | Validate a formula expression before applying |
165308
| `update_formula_field` | Update the formula text of an existing field |
166309
| `update_field_config` | Update configuration of any computed field |
167310
| `rename_field` | Rename a field with pre-validation |
168-
| `delete_field` | Delete with safety guards and dependency checks |
311+
| `delete_field` | Delete with safety guards and a compact dependency summary |
169312
| `duplicate_field` | Clone a field, optionally copying cell values |
313+
| `update_field_description` | Set or update a field's description text |
170314

171315
### View Configuration (11)
172316

@@ -177,20 +321,14 @@ Sessions are cached in `~/.airtable-user-mcp/` and reused automatically.
177321
| `rename_view` | Rename a view |
178322
| `delete_view` | Delete a view (cannot delete last view) |
179323
| `update_view_description` | Set or clear a view's description |
180-
| `update_view_filters` | Set filter conditions with AND/OR conjunctions |
324+
| `update_view_filters` | Set or append filter conditions (AND/OR, nested groups, `is`/`isNot` auto-normalized) |
181325
| `reorder_view_fields` | Change column order |
182326
| `show_or_hide_view_columns` | Toggle column visibility |
183327
| `apply_view_sorts` | Set or clear sort conditions |
184328
| `update_view_group_levels` | Set or clear grouping |
185329
| `update_view_row_height` | Change row height (small / medium / large / xlarge) |
186330

187-
### Field Metadata (1)
188-
189-
| Tool | Description |
190-
|:-----|:------------|
191-
| `update_field_description` | Set or update a field's description text |
192-
193-
### Extension Management (5)
331+
### Extension Management (7)
194332

195333
| Tool | Description |
196334
|:-----|:------------|
@@ -243,8 +381,9 @@ Args: {
243381

244382
## Safety
245383

246-
- **Destructive operations** (`delete_field`, `delete_view`, `remove_extension`) include built-in safety guards
247-
- `delete_field` requires both `fieldId` **and** `expectedName`, and checks for downstream dependencies before deleting
384+
- **Destructive operations** (`delete_table`, `delete_field`, `delete_view`, `remove_extension`) include built-in safety guards
385+
- `delete_table` and `delete_field` both require an `expectedName` parameter that must match the current name exactly — prevents accidentally deleting the wrong object after a rename
386+
- `delete_field` checks for downstream dependencies and returns a compact summary (`viewGroupings`, `viewSorts`, `viewFilters`, `fields`) before committing; set `force: true` to delete anyway
248387
- Formula validation is available and recommended before creating/updating formulas
249388
- All tools accept `debug: true` for raw response inspection
250389

0 commit comments

Comments
 (0)