@rashidazarang/airtable-mcp 1.2.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,10 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/CLAUDE_INTEGRATION.md

@@ -0,0 +1,109 @@
+# Claude/Windsurf Integration Guide
+
+This guide explains how to set up the Airtable MCP for use with Claude (including Anthropic's tools and in VSCode extensions like Windsurf).
+
+## Setup for Claude
+
+### Requirements
+
+- Node.js v14 or higher
+- An Airtable account with Personal Access Token
+- An Airtable base you want to connect to
+
+### Configuration
+
+Claude requires the configuration to be specified in JSON format. Here's how to set up the configuration for Claude:
+
+1. In Claude settings, add a new MCP server with these settings:
+   - Name: `airtable-mcp`
+   - Command: `npx`
+   - Arguments:
+     ```
+     -y @smithery/cli@latest run @rashidazarang/airtable-mcp --config {"airtable_token":"your_token_here","base_id":"your_base_id_here"}
+     ```
+
+2. **IMPORTANT: JSON Format**  
+   Make sure the JSON in the `--config` parameter is properly formatted:
+   - No line breaks
+   - No extra backslashes
+   - No surrounding quotes
+
+### Troubleshooting JSON Issues
+
+If you encounter the error `Unexpected token 'F', "Found & ig"... is not valid JSON`, try these fixes:
+
+1. **Method 1: Simplify JSON** - Remove any complex characters from your token and try again.
+
+2. **Method 2: Escape Properly** - Make sure you format the command with proper escaping:
+   ```
+   -y @smithery/cli@latest run @rashidazarang/airtable-mcp --config {\"airtable_token\":\"your_token_here\",\"base_id\":\"your_base_id_here\"}
+   ```
+
+3. **Method 3: Use Separate Parameters** - Instead of using --config, use individual parameters:
+   ```
+   -y @smithery/cli@latest run @rashidazarang/airtable-mcp --token your_token_here --base your_base_id_here
+   ```
+
+## Setup for Windsurf
+
+Windsurf users should use a dedicated config file to avoid JSON parsing issues:
+
+1. Create a file called `mcp_config.json` with:
+   ```json
+   {
+     "mcpServers": {
+       "AIRTABLE": {
+         "command": "npx",
+         "args": [
+           "-y",
+           "@smithery/cli@latest",
+           "run",
+           "@rashidazarang/airtable-mcp",
+           "--token",
+           "your_token_here",
+           "--base",
+           "your_base_id_here"
+         ]
+       }
+     }
+   }
+   ```
+
+2. In Windsurf settings, configure it to use this file.
+
+## Common Issues
+
+### AbortController Error
+
+If you see an error like `ReferenceError: AbortController is not defined`, this is because you're using an older version of Node.js that doesn't include this feature. Options to fix:
+
+1. **Update Node.js** (recommended) - Install Node.js v15+ which includes AbortController natively.
+
+2. **Use Polyfill** - New versions of our MCP (1.1.0+) automatically add a polyfill for older Node versions.
+
+### Server Disconnected or Timeout Errors
+
+1. Check that your Airtable token is valid and has the necessary permissions
+2. Ensure you have proper internet connectivity
+3. Try restarting the MCP server
+4. Check the logs for any specific error messages
+
+## Using the MCP with Claude
+
+Once connected, you can use the following tools:
+
+- `list_bases` - Show available Airtable bases
+- `list_tables` - List tables in the current base
+- `list_records` - Get records from a specific table
+- `create_records` - Add new records to a table
+- `update_records` - Modify existing records
+
+For example, in Claude, you might ask:
+"Please list all tables in my Airtable base and then show me records from the 'Contacts' table."
+
+## Support
+
+If you continue to experience issues, please report them on GitHub with:
+- Error messages
+- Node.js version (`node -v`)
+- Operating system details 

package/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to Airtable MCP
+
+Thank you for your interest in contributing to Airtable MCP! This guide will help you get started with contributing to this project.
+
+## Development Setup
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/rashidazarang/airtable-mcp.git
+   cd airtable-mcp
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Environment setup**:
+   Create a `.env` file in the root directory with your Airtable API token:
+   ```
+   AIRTABLE_PERSONAL_ACCESS_TOKEN=your_token_here
+   AIRTABLE_BASE_ID=optional_default_base_id
+   ```
+
+## Running the Server
+
+You can run the server directly with Python:
+
+```bash
+python3.10 inspector_server.py --token "your_token" --base "your_base_id"
+```
+
+Or through the Node.js wrapper:
+
+```bash
+node index.js --token "your_token" --base "your_base_id"
+```
+
+## Testing
+
+Run the test client to verify your Airtable API access:
+
+```bash
+python3.10 test_client.py
+```
+
+## Pull Request Process
+
+1. **Fork the Repository** on GitHub.
+
+2. **Create a Branch** for your feature or bugfix.
+
+3. **Make Changes** according to the project style guidelines.
+
+4. **Test Thoroughly** to ensure your changes work as expected.
+
+5. **Document Changes** in the README.md if necessary.
+
+6. **Submit a Pull Request** to the main repository.
+
+## Coding Guidelines
+
+- Follow Python PEP 8 style guidelines
+- Write docstrings for all functions, classes, and modules
+- Include type hints for function parameters and return values
+- Write clear commit messages
+
+## Adding New Tools
+
+When adding new Airtable API tools:
+
+1. Add the tool function to `inspector_server.py` using the `@app.tool()` decorator
+2. Define clear parameter and return types
+3. Provide a descriptive docstring for the tool
+4. Update the inspector.py file to include the new tool in the JSON schema
+5. Add error handling for API requests
+6. Update the README.md to document the new tool
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the project's MIT License. 

package/Dockerfile

@@ -0,0 +1,39 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install Node.js for the NPX functionality
+RUN apt-get update && \
+    apt-get install -y curl gnupg && \
+    curl -fsSL https://deb.nodesource.com/setup_18.x | bash - && \
+    apt-get install -y nodejs && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy package files first (for better layer caching)
+COPY package.json /app/
+COPY package-lock.json /app/
+
+# Install Node.js dependencies
+RUN npm install
+
+# Copy Python requirements and install
+COPY requirements.txt /app/
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy source code
+COPY index.js /app/
+COPY inspector.py /app/
+COPY inspector_server.py /app/
+COPY airtable_mcp/ /app/airtable_mcp/
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV PYTHONUNBUFFERED=1
+
+# Expose the port the server might run on
+EXPOSE 3000
+
+# Start the server in STDIO mode by default
+# Smithery will override this with their own command
+CMD ["python3", "inspector_server.py"] 

package/INSTALLATION.md

@@ -0,0 +1,183 @@
+# Installation
+
+Airtable MCP embeds Airtable database connectivity directly into your AI-powered code editor
+
+## Getting Started
+
+Built by Rashid Azarang,
+
+Airtable MCP gives AI code editors and agents the ability to access and manipulate your Airtable databases for powerful data management capabilities - all in a secure manner with your own API tokens.
+
+With this MCP server tool, you can enable AI code editors and agents to have access to:
+
+* List and access all your Airtable bases
+* Browse tables, fields, and record data
+* Create, read, update, and delete records
+* Export and manipulate schemas
+* Perform complex queries against your data
+* Create data migration mappings
+* Analyze and transform your Airtable data
+
+That way, you can simply tell Cursor or any AI code editor with MCP integrations:
+
+"Show me all the tables in my Airtable base"
+
+"Find all records from the Customers table where the status is Active and the last purchase was after January 1st"
+
+"Create a new record in the Products table with these fields..."
+
+"Export the schema of my current Airtable base"
+
+"Help me create a mapping between these two tables for data migration"
+
+---
+
+## Requirements
+
+* Node.js 14+ installed on your machine
+* Python 3.10+ installed on your machine (automatically detected)
+* Airtable Personal Access Token (API Key)
+* MCP Client Application (Cursor, Claude Desktop, Cline, Zed, etc.)
+
+**Note**: Model Context Protocol (MCP) is specific to Anthropic models. When using an editor like Cursor, make sure to enable composer agent with Claude 3.5 Sonnet selected as the model.
+
+---
+
+## Installation
+
+### 1. Install via Smithery (Easiest)
+
+The easiest way to install Airtable MCP is through Smithery:
+
+1. Visit [Smithery](https://smithery.ai)
+2. Search for "@rashidazarang/airtable-mcp"
+3. Click "Install" and follow the prompts to configure with your Airtable token and base ID
+
+### 2. Install via NPX (Alternative)
+
+Another simple way to install and use Airtable MCP is via NPX:
+
+```bash
+# Install globally
+npm install -g airtable-mcp
+
+# Or use directly with npx (no installation needed)
+npx airtable-mcp --token YOUR_AIRTABLE_TOKEN --base YOUR_BASE_ID
+```
+
+### 3. Get Your Airtable API Token
+
+1. Log in to your Airtable account
+2. Go to your [Account Settings](https://airtable.com/account)
+3. Navigate to the "API" section
+4. Create a Personal Access Token with appropriate permissions
+5. Copy your token to use in the configuration
+
+### 4. Configure Your MCP Client
+
+#### For Cursor:
+
+1. Go to Cursor Settings
+2. Navigate to Features, scroll down to MCP Servers and click "Add new MCP server"
+3. Give it a unique name (airtable-tools), set type to "command" and set the command to:
+
+**For macOS/Linux/Windows:**
+```bash
+npx airtable-mcp --token YOUR_AIRTABLE_TOKEN --base YOUR_BASE_ID
+```
+
+Replace `YOUR_AIRTABLE_TOKEN` with your Airtable Personal Access Token and `YOUR_BASE_ID` with your default Airtable base ID (optional).
+
+#### For Advanced Users via ~/.cursor/mcp.json:
+
+Edit your `~/.cursor/mcp.json` file to include:
+
+```json
+{
+  "mcpServers": {
+    "airtable-tools": {
+      "command": "npx",
+      "args": [
+        "airtable-mcp",
+        "--token", "YOUR_AIRTABLE_TOKEN",
+        "--base", "YOUR_BASE_ID"
+      ]
+    }
+  }
+}
+```
+
+### 5. Verify Connection
+
+1. Restart your MCP client (Cursor, etc.)
+2. Create a new query using the Composer Agent with Claude 3.5 Sonnet model
+3. Ask something like "List my Airtable bases" or "Show me the tables in my current base"
+4. You should see a response with your Airtable data
+
+### 6. For Production Use (Optional)
+
+For continuous availability, you can set up Airtable MCP using PM2:
+
+```bash
+# Install PM2 if you don't have it
+npm install -g pm2
+
+# Create a PM2 config file
+echo 'module.exports = {
+  apps: [
+    {
+      name: "airtable-mcp",
+      script: "npx",
+      args: [
+        "airtable-mcp",
+        "--token", "YOUR_AIRTABLE_TOKEN",
+        "--base", "YOUR_BASE_ID"
+      ],
+      env: {
+        PATH: process.env.PATH,
+      },
+    },
+  ],
+};' > ecosystem.config.js
+
+# Start the process
+pm2 start ecosystem.config.js
+
+# Set it to start on boot
+pm2 startup
+pm2 save
+```
+
+---
+
+## Troubleshooting
+
+Here are some common issues and their solutions:
+
+### Error: Unable to connect to Airtable API
+
+- Double-check your Airtable API token is correct and has sufficient permissions
+- Verify your internet connection
+- Check if Airtable API is experiencing downtime
+
+### Issue: MCP server not connecting
+
+- Make sure Node.js 14+ and Python 3.10+ are installed and in your PATH
+- Try specifying a specific version: `npx airtable-mcp@latest`
+- Check the Cursor logs for any connection errors
+
+### Error: Base not found
+
+- Verify your base ID is correct
+- Make sure your API token has access to the specified base
+- Try listing all bases first to confirm access
+
+### Issue: Permission denied errors
+
+- Make sure your token has the necessary permissions for the operations you're trying to perform
+- Check if you're attempting operations on tables/bases that your token doesn't have access to
+
+### For more help
+
+- Open an issue on the [GitHub repository](https://github.com/rashidazarang/airtable-mcp/issues)
+- Check the Airtable API documentation for any API-specific errors 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rashid Azarang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.