Effect Airtable Server

A production-ready Model Context Protocol server for Airtable, built with Effect for type-safe, composable, and robust API interactions. This server enables programmatic management of Airtable bases, tables, fields, and records through Claude Desktop or other MCP clients.

Why Effect?

This server leverages the Effect library to provide:

• Type Safety: Full end-to-end type safety from input validation to output serialization
• Error Handling: Structured error types with automatic validation and retries
• Composability: Modular tool architecture with reusable validation pipelines
• Testability: Pure functions and Effect-based testing without mocking
• Reliability: Contract-driven design catches API changes at validation boundaries

Unlike traditional implementations, this server features:

• Staged Table Creation: Builds complex tables incrementally to minimize API failures
• Schema Validation: Zod schemas ensure correctness at runtime
• Automatic Retries: Effect-based retry logic for transient failures
• Developer Experience: Comprehensive error messages and type inference

Requirements: Node.js

1. Install Node.js (version 18 or higher) and npm from nodejs.org
2. Verify installation:

   node --version
   npm --version
   

⚠️ Important: Before running, make sure to setup your Airtable API key

Obtaining an Airtable API Key

1. Log in to your Airtable account at airtable.com
2. Create a personal access token at Airtable's Builder Hub
3. In the Personal access token section select these scopes:
   • data.records:read
   • data.records:write
   • schema.bases:read
   • schema.bases:write
4. Select the workspace or bases you want to give access to the personal access token
5. Keep this key secure - you'll need it for configuration

Installation

Method 1: Using npx (Recommended)

1. Navigate to the Claude configuration directory:

   • Windows: C:\Users\NAME\AppData\Roaming\Claude
   • macOS: ~/Library/Application Support/Claude/

   You can also find these directories inside the Claude Desktop app: Claude Desktop > Settings > Developer > Edit Config

2. Create or edit claude_desktop_config.json:

{
  "mcpServers": {
    "airtable-effect": {
      "command": "npx",
      "args": ["@kastalien-research/effect-airtable-mcp"],
      "env": {
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: For Windows paths, use double backslashes (\) or forward slashes (/).

Method 2: Local Development Installation

If you want to contribute or modify the code:

# Clone the repository
git clone https://github.com/glassBead-tc/effect-airtable-mcp.git
cd effect-airtable-mcp

# Install dependencies
npm install

# Build the server
npm run build

# Run tests
npm test

# Run locally
node build/index.js

Then modify the Claude Desktop configuration file to use the local installation:

{
  "mcpServers": {
    "airtable-effect": {
      "command": "node",
      "args": ["/absolute/path/to/effect-airtable-mcp/build/index.js"],
      "env": {
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Verifying Installation

1. Start Claude Desktop
2. The Airtable MCP server should be listed in the "Connected MCP Servers" section
3. Test with a simple command:

List all bases

Architecture

Effect-Based Design

This server uses a contract-driven architecture powered by Effect:

// Every tool follows this pattern:
ToolExecutor {
  1. Validate Input (Zod schema)
  2. Execute Operation (Effect workflow)
  3. Validate Output (Zod schema)
  4. Check Postconditions (business rules)
  → Return typed result or structured error
}

Key Components:

• ToolExecutor: Generic execution framework with validation pipeline
• mcp-adapter: Bridges Effect workflows to MCP protocol
• Schema Modules: Zod schemas for all inputs/outputs (bases, tables, fields, records)
• Tool Modules: Pure Effect-based operations with no side effects until execution

Error Handling:

• InputValidationError: Invalid tool arguments
• OutputValidationError: Unexpected API response (catches breaking changes)
• AirtableApiError: HTTP errors with context and retry logic
• PostconditionError: Business rule violations

See src/docs/effect-architecture.md for detailed documentation.

Claude Code Channel

The server ships a second entrypoint, src/channel/server.ts, that turns it into a Claude Code Channel: a stdio MCP server that pushes events into a live Claude Code session via notifications/claude/channel, so Claude can react to things happening outside the terminal with full codebase context. It exposes the same Code Mode tools (search + execute), so Claude can act on Airtable the moment an event arrives.

Events come from two sources:

1. Local HTTP receiver — anything that can reach localhost can push an event:

   curl -X POST http://127.0.0.1:3031/event \
     -H 'Content-Type: application/json' \
     -d '{"content": "CI build failed on main", "meta": {"severity": "high"}}'
   

   Claude receives it as <channel source="airtable-effect-channel" origin="http" severity="high">CI build failed on main</channel>.

2. Airtable webhook poller (optional) — set AIRTABLE_WEBHOOK_BASE_ID and AIRTABLE_WEBHOOK_ID and the channel polls the webhook payloads endpoint for record/table changes. No public URL or tunnel needed — create the webhook without a notificationUrl and the poller drains its payloads (and refreshes it every 6 hours so it doesn't expire).

Setup

Requires Claude Code v2.1.80+ with claude.ai login. The channel is already registered in .mcp.json as airtable-effect-channel; launch Claude Code with:

claude --channels --dangerously-load-development-channels airtable-effect-channel

(The --dangerously-load-development-channels flag is needed during the research preview, when custom channels aren't on the approved allowlist.)

Configuration

Variable	Default	Purpose
AIRTABLE_API_KEY	— (required)	Same key the main server uses
CHANNEL_HTTP_PORT	3031	Port for the local event receiver (binds 127.0.0.1 only)
CHANNEL_HTTP_TOKEN	unset	If set, POST /event requires Authorization: Bearer <token>
AIRTABLE_WEBHOOK_BASE_ID	unset	Base to poll webhook payloads from
AIRTABLE_WEBHOOK_ID	unset	Webhook to poll (ach...)
AIRTABLE_WEBHOOK_POLL_SECONDS	15	Poll interval

The channel is one-way: there is no reply tool. Claude responds by acting — querying or mutating Airtable through execute, or editing the working directory.

Features

Available Operations

Base Management

• list_bases: List all accessible Airtable bases
• list_tables: List all tables in a base
• create_table: Create a new table with fields
• update_table: Update a table's name or description

Field Management

• create_field: Add a new field to a table
• update_field: Modify an existing field

Record Operations

• list_records: Retrieve records from a table
• create_record: Add a new record
• update_record: Modify an existing record
• delete_record: Remove a record
• search_records: Find records matching criteria
• get_record: Get a single record by its ID

Field Types

• singleLineText: Single line text field
• multilineText: Multi-line text area
• email: Email address field
• phoneNumber: Phone number field
• number: Numeric field with optional precision
• currency: Money field with currency symbol
• date: Date field with format options
• singleSelect: Single choice from options
• multiSelect: Multiple choices from options

Field Colors

Available colors for select fields:

• blueBright, redBright, greenBright
• yellowBright, purpleBright, pinkBright
• grayBright, cyanBright, orangeBright
• blueDark1, greenDark1

Contributing

We welcome contributions to improve the Effect Airtable MCP server!

Quick Start

1. Fork and clone:

   git clone https://github.com/your-username/effect-airtable-mcp.git
   cd effect-airtable-mcp
   npm install
   

2. Create a feature branch:

   git checkout -b feature/your-feature-name
   

3. Make your changes following Effect patterns (see src/docs/effect-architecture.md)

4. Run tests and linting:

   npm test
   npm run lint
   npm run format:check
   

5. Commit and push:

   git add .
   git commit -m "feat: add your feature description"
   git push origin feature/your-feature-name
   

6. Open a Pull Request at https://github.com/glassBead-tc/effect-airtable-mcp

Development Guidelines

• Use Effect patterns: All tools use ToolExecutor with Zod validation
• Type safety: No any types, strict TypeScript enabled
• Testing: Write Effect-based tests (no mocking needed)
• Error handling: Use structured ToolError types
• Documentation: Update schemas and tool descriptions
• Commits: Follow semantic commit messages (feat/fix/docs/refactor)

Getting Help

• Open an issue for bugs or feature requests
• Join discussions in existing issues
• Ask questions in pull requests

Your contributions help make this tool better for everyone. Whether it's:

• Adding new features
• Fixing bugs
• Improving documentation
• Suggesting enhancements

We appreciate your help in making the Airtable MCP server more powerful and user-friendly!

License

MIT

---

Made with ❤️ by the Airtable MCP community