# AITable MCP Server
Model Context Protocol (MCP) server for integrating with AITable platform.
> **⚠️ Important:** AITable has been discontinued. If you're looking to migrate to Bika (the successor platform), check out the [Bika MCP Server](https://github.com/hamchowderr/bika-mcp).
>
> **AITable LTD Holders:** Claim your free Bika account by filling out [this migration form](https://bika.ai/space/spcND68gdMMZBmGK67gvqNVx/node/fom8XyUsPAmUVwlgpq8bFxPw) (available only for AITable LTD users).
## Overview
This MCP server provides integration with AITable's API, enabling AI assistants to:
- Query and filter datasheet records
- Create, update, and delete records
- Upload and manage attachments
- Work with fields, views, and nodes
- Create embeddable links
## Features
- **Records Management**: Full CRUD operations on AITable records
- **Fields Management**: Create, query, and delete fields
- **Views & Nodes**: Access datasheet views and workspace nodes
- **Attachments**: Upload and manage files
- **Embed Links**: Create and manage embeddable links
- **Formula Resources**: Access AITable formula documentation
## Prerequisites
- Node.js >= 18.0.0
- npm or pnpm
- AITable account with API access token
## Installation
### Option 1: Install via npm (Recommended)
Once published, you can install directly via npx:
```bash
# No installation needed! Run directly with npx
npx aitable-mcp
```
### Option 2: Install from Source
```bash
# Clone the repository
git clone https://github.com/hamchowderr/aitable-mcp.git
cd aitable-mcp
# Install dependencies
npm install
# Build the project
npm run build
```
## Configuration
### Environment Variables
The server requires the following environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `AITABLE_API_TOKEN` | Yes | Your AITable API access token |
| `SPACE_ID` | Yes | Your AITable space ID |
### Setting Environment Variables
**Option 1: Environment variables**
```bash
# Windows
set AITABLE_API_TOKEN=your-api-token-here
set SPACE_ID=your-space-id
# macOS/Linux
export AITABLE_API_TOKEN="your-api-token-here"
export SPACE_ID="your-space-id"
```
**Option 2: Create a `.env` file**
Create a `.env` file in the project root:
```env
AITABLE_API_TOKEN=your-api-token-here
SPACE_ID=your-space-id
```
## Usage
### Option 1: Claude Desktop (Stdio Transport)
The recommended way to use this MCP server is with Claude Desktop using stdio transport.
#### Configuration File Locations
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Using npx (Recommended)
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"aitable": {
"command": "npx",
"args": ["-y", "aitable-mcp"],
"env": {
"AITABLE_API_TOKEN": "your-token-here",
"SPACE_ID": "your-space-id"
}
}
}
}
```
#### Using Local Installation
For development or local installations:
```json
{
"mcpServers": {
"aitable": {
"command": "node",
"args": ["C:\\absolute\\path\\to\\aitable-mcp\\dist\\stdio-server.js"],
"env": {
"AITABLE_API_TOKEN": "your-token-here",
"SPACE_ID": "your-space-id"
}
}
}
}
```
**Important**: Restart Claude Desktop after updating the configuration.
### Option 2: Testing with MCP Inspector
Test your server locally with the official MCP Inspector:
```bash
# Run the inspector
npm run inspector
# Or run directly
npx @modelcontextprotocol/inspector dist/stdio-server.js
```
This will:
1. Start the MCP server
2. Launch the inspector web interface at `http://localhost:6274`
3. Allow you to test tools, resources, and prompts interactively
### Option 3: Running Standalone (Stdio)
Run the server directly for stdio transport:
```bash
# Build and start
npm run build
npm start
# Development mode with watch
npm run dev
```
### Option 4: Custom Connector (HTTP Transport via Vercel)
Deploy as a custom connector for HTTP-based MCP access.
#### Deploy to Vercel
1. **Initial Deployment**:
```bash
# Install Vercel CLI if needed
npm install -g vercel
# Deploy to Vercel
npx vercel@latest
```
2. **Production Deployment**:
```bash
npx vercel@latest --prod
```
3. **Set Environment Variables**:
In your Vercel project settings (Settings → Environment Variables), add:
- `AITABLE_API_TOKEN` - Your AITable API token (required for authenticating with AITable)
- `SPACE_ID` - Your AITable space ID (required)
**Important**: Ensure both variables are enabled for **all environments** (Production, Preview, and Development). If Preview is unchecked, preview deployment URLs will fail with "Connection refused".
4. **Disable Deployment Protection (Required for MCP)**:
In your Vercel project settings (Settings → Deployment Protection):
- **Turn OFF "Vercel Authentication"**
- This is required for Claude Desktop and other MCP clients to connect
- Your data remains secure through the API token configured in step 3
5. **Configure as Custom Connector in Claude Desktop**:
**IMPORTANT**: Custom connectors must be configured via the Claude Desktop UI, NOT via `claude_desktop_config.json`.
**To add the custom connector:**
1. Open Claude Desktop
2. Go to **Settings → Connectors**
3. Click **Add Custom Connector**
4. Enter your deployment URL: `https://your-project.vercel.app/mcp`
5. Save and restart Claude Desktop
**Note**: Make sure to include `/mcp` at the end of the URL!
6. **Test the Deployment**:
```bash
# Test with the test script
node scripts/test-streamable-http-client.mjs https://your-project.vercel.app
```
#### Deployment Options
**Stdio vs HTTP Transport:**
- **Stdio (Recommended)**: Lower latency, direct process communication, best for Claude Desktop
- **HTTP (Custom Connector)**: Centralized deployment, multiple clients, better for cloud deployments
**Which to use?**
- Use **stdio** for local Claude Desktop integration
- Use **HTTP** for centralized deployments, multiple users, or cloud-based AI clients
## Security
### Authentication Overview
This MCP server uses different authentication strategies depending on the transport:
**Stdio Transport (Recommended for Personal Use)**
- Uses environment variables for AITable API authentication
- No client authentication required (local process, no network exposure)
- Most secure for personal use
- Configure via `claude_desktop_config.json`
**HTTP Transport (Custom Connector)**
- Deployed to Vercel as a serverless function
- Requires disabling Vercel Deployment Protection
- CORS-enabled for browser-based access
- Environment variables stored securely in Vercel
### Security Best Practices
**IMPORTANT:**
- ⚠️ Keep your `AITABLE_API_TOKEN` secret - it grants full access to your AITable data
- ⚠️ Keep your deployment URL private - share only with trusted users
- ⚠️ **Disable Vercel Deployment Protection** for MCP clients to connect
- ✅ Use environment variables in Vercel (never commit tokens to git)
- ✅ Rotate your API token periodically
- ✅ Monitor access logs in Vercel dashboard
- ✅ For personal use, prefer stdio transport over HTTP
## Architecture
This MCP server supports **dual transport** following official MCP patterns:
### Stdio Transport (src/stdio-server.ts)
- Primary entry point for Claude Desktop
- Direct process communication via stdin/stdout
- Low latency, perfect for local development
- Executable via `npx` or `node dist/stdio-server.js`
### HTTP Transport (api/server.ts)
- Vercel serverless function with CORS support
- Uses `mcp-handler` library for HTTP transport
- Supports custom connector deployments
- All requests handled at root path with catch-all routing
Both transports share the same core business logic while providing different communication mechanisms.
## Project Structure
```
aitable-mcp/
├── src/
│ ├── stdio-server.ts # Stdio entry point
│ ├── http-server.ts # Local HTTP server for testing
│ ├── aitable-tools.ts # MCP tool implementations
│ ├── formula-resource.ts # Formula documentation provider
│ ├── types.ts # TypeScript type definitions
│ └── *.md # Formula documentation files
├── api/
│ └── server.ts # HTTP entry point (Vercel)
├── public/
│ └── index.html # Landing page
├── scripts/
│ ├── test-client.mjs # SSE transport tester
│ └── test-streamable-http-client.mjs # HTTP transport tester
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
├── vercel.json # Vercel configuration
└── README.md
```
## Available Tools (16)
The MCP server provides comprehensive AITable integration tools:
### Records Management
- `get_records` - Query records with filtering, sorting, and pagination
- `create_records` - Create new records (max 10 per request)
- `update_records` - Update existing records (max 10 per request)
- `delete_records` - Delete records (max 10 per request)
### Fields Management
- `get_fields` - Get field metadata from datasheets
- `create_field` - Create new fields in datasheets
- `delete_field` - Delete fields from datasheets
### Views & Datasheets
- `get_views` - Get views from datasheets
- `create_datasheet` - Create new datasheets with custom fields
### Attachments
- `upload_attachment` - Upload files to datasheets
### Nodes & Workspace
- `get_node_list` - Get list of files in workspace
- `search_nodes` - Search nodes by type, permissions, and keywords
- `get_node_detail` - Get detailed information about specific nodes
### Embed Links
- `create_embed_link` - Create embeddable links for nodes
- `get_embed_links` - List all embed links for a node
- `delete_embed_link` - Delete/disable embed links
## Available Resources (8)
Formula reference documentation:
- `formula_overview` - Quick reference guide to AITable formulas
- `formula_operators` - AITable formula operators
- `formula_numeric` - AITable numeric functions
- `formula_string` - AITable string functions
- `formula_logical` - AITable logical functions
- `formula_date` - AITable date/time functions
- `formula_array` - AITable array functions
- `field_colors` - AITable field color reference
## Development
```bash
# Clean build artifacts
npm run clean
# Build TypeScript
npm run build
# Watch mode for development
npm run dev
# Test HTTP server locally
npm run dev:http
# Test with Vercel dev server
npm run dev:vercel
```
## Contributing
Contributions are welcome! Please ensure your changes maintain the dual-transport architecture.
### For AI-Assisted Development
If you're using Claude Code or other AI assistants to work on this codebase, run `/init` to generate a `CLAUDE.md` file with architectural guidance and development patterns specific to this project.
## License
MIT
## Related Projects
### Bika MCP Server
AITable has been discontinued. For the successor platform, check out the [Bika MCP Server](https://github.com/hamchowderr/bika-mcp). It provides similar MCP integration for Bika.ai, making it easy to migrate your workflows.
## Resources
- [AITable](https://aitable.ai)
- [Bika.ai](https://bika.ai) - AITable successor platform
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Bika MCP Server](https://github.com/hamchowderr/bika-mcp) - MCP server for Bika.ai integration