@rashidazarang/airtable-mcp 1.2.0

package/inspector.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+MCP Tool Inspector
+-----------------
+A simple script to list tools in a format Smithery can understand
+"""
+import json
+
+# Define the tools manually
+tools = [
+    {
+        "name": "list_bases",
+        "description": "List all accessible Airtable bases",
+        "parameters": {
+            "type": "object",
+            "properties": {},
+            "required": []
+        },
+        "returns": {
+            "type": "string"
+        }
+    },
+    {
+        "name": "list_tables",
+        "description": "List all tables in the specified base or the default base",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string",
+                    "description": "Optional base ID to use instead of the default"
+                }
+            },
+            "required": []
+        },
+        "returns": {
+            "type": "string"
+        }
+    },
+    {
+        "name": "list_records",
+        "description": "List records from a table with optional filtering",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "table_name": {
+                    "type": "string",
+                    "description": "Name of the table to list records from"
+                },
+                "max_records": {
+                    "type": "integer",
+                    "description": "Maximum number of records to return (default: 100)"
+                },
+                "filter_formula": {
+                    "type": "string",
+                    "description": "Optional Airtable formula to filter records"
+                }
+            },
+            "required": ["table_name"]
+        },
+        "returns": {
+            "type": "string"
+        }
+    },
+    {
+        "name": "get_record",
+        "description": "Get a specific record from a table",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "table_name": {
+                    "type": "string",
+                    "description": "Name of the table"
+                },
+                "record_id": {
+                    "type": "string",
+                    "description": "ID of the record to retrieve"
+                }
+            },
+            "required": ["table_name", "record_id"]
+        },
+        "returns": {
+            "type": "string"
+        }
+    },
+    {
+        "name": "create_records",
+        "description": "Create records in a table from JSON string",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "table_name": {
+                    "type": "string",
+                    "description": "Name of the table"
+                },
+                "records_json": {
+                    "type": "string",
+                    "description": "JSON string containing the records to create"
+                }
+            },
+            "required": ["table_name", "records_json"]
+        },
+        "returns": {
+            "type": "string"
+        }
+    },
+    {
+        "name": "update_records",
+        "description": "Update records in a table from JSON string",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "table_name": {
+                    "type": "string",
+                    "description": "Name of the table"
+                },
+                "records_json": {
+                    "type": "string",
+                    "description": "JSON string containing the records to update with IDs"
+                }
+            },
+            "required": ["table_name", "records_json"]
+        },
+        "returns": {
+            "type": "string"
+        }
+    },
+    {
+        "name": "set_base_id",
+        "description": "Set the current Airtable base ID",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "base_id": {
+                    "type": "string",
+                    "description": "Base ID to set as the current base"
+                }
+            },
+            "required": ["base_id"]
+        },
+        "returns": {
+            "type": "string"
+        }
+    }
+]
+
+# Print the tools as JSON
+print(json.dumps({"tools": tools}, indent=2)) 

package/inspector_server.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+"""
+Airtable MCP Inspector Server
+-----------------------------
+A simple MCP server that implements the Airtable tools
+"""
+import os
+import sys
+import json
+import logging
+import requests
+import argparse
+from typing import Optional, Dict, Any, List
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:
+    print("Error: MCP SDK not found. Please install with 'pip install mcp'")
+    sys.exit(1)
+
+# Parse command line arguments
+def parse_args():
+    parser = argparse.ArgumentParser(description="Airtable MCP Server")
+    parser.add_argument("--token", dest="api_token", help="Airtable Personal Access Token")
+    parser.add_argument("--base", dest="base_id", help="Airtable Base ID")
+    parser.add_argument("--config", dest="config_json", help="Configuration as JSON (for Smithery integration)")
+    return parser.parse_args()
+
+# Set up logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("airtable-mcp")
+
+# Parse arguments
+args = parse_args()
+
+# Handle config JSON from Smithery if provided
+config = {}
+if args.config_json:
+    try:
+        # Strip any trailing quotes or backslashes that might be present
+        config_str = args.config_json.rstrip('\\"')
+        # Additional sanitization for JSON format
+        config_str = config_str.strip()
+        # Handle escaped quotes
+        if config_str.startswith('"') and config_str.endswith('"'):
+            config_str = config_str[1:-1]
+        # Fix escaped quotes within JSON
+        config_str = config_str.replace('\\"', '"')
+        # Replace escaped backslashes
+        config_str = config_str.replace('\\\\', '\\')
+        
+        logger.info(f"Parsing sanitized config: {config_str}")
+        config = json.loads(config_str)
+        logger.info(f"Successfully parsed config: {config}")
+    except json.JSONDecodeError as e:
+        logger.error(f"Failed to parse config JSON: {e}")
+        logger.error(f"Raw config string: {args.config_json}")
+        # Try one more approach - sometimes config is double-quoted JSON
+        try:
+            # Try to interpret as Python string literal
+            import ast
+            literal_str = ast.literal_eval(f"'''{args.config_json}'''")
+            config = json.loads(literal_str)
+            logger.info(f"Successfully parsed config using ast: {config}")
+        except Exception as ast_error:
+            logger.error(f"Failed alternate parsing method: {ast_error}")
+
+# Create MCP server
+app = FastMCP("Airtable Tools")
+
+# Get token from arguments, config, or environment
+token = args.api_token or config.get("airtable_token", "") or os.environ.get("AIRTABLE_PERSONAL_ACCESS_TOKEN", "")
+# Clean up token if it has trailing quote
+if token and token.endswith('"'):
+    token = token[:-1]
+    
+base_id = args.base_id or config.get("base_id", "") or os.environ.get("AIRTABLE_BASE_ID", "")
+
+if not token:
+    logger.warning("No Airtable API token provided. Use --token, --config, or set AIRTABLE_PERSONAL_ACCESS_TOKEN environment variable.")
+else:
+    logger.info(f"Using Airtable token: {token[:5]}...{token[-5:]}")
+
+if base_id:
+    logger.info(f"Using base ID: {base_id}")
+else:
+    logger.warning("No base ID provided. Use --base, --config, or set AIRTABLE_BASE_ID environment variable.")
+
+# Helper functions for Airtable API calls
+async def api_call(endpoint, method="GET", data=None, params=None):
+    """Make an Airtable API call"""
+    if not token:
+        return {"error": "No Airtable API token provided. Use --token, --config, or set AIRTABLE_PERSONAL_ACCESS_TOKEN environment variable."}
+    
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    }
+    
+    url = f"https://api.airtable.com/v0/{endpoint}"
+    
+    try:
+        if method == "GET":
+            response = requests.get(url, headers=headers, params=params)
+        elif method == "POST":
+            response = requests.post(url, headers=headers, json=data)
+        elif method == "PATCH":
+            response = requests.patch(url, headers=headers, json=data)
+        elif method == "DELETE":
+            response = requests.delete(url, headers=headers, params=params)
+        else:
+            raise ValueError(f"Unsupported method: {method}")
+        
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        logger.error(f"API call error: {str(e)}")
+        return {"error": str(e)}
+
+# Define MCP tool functions
+@app.tool()
+async def list_bases() -> str:
+    """List all accessible Airtable bases"""
+    if not token:
+        return "Please provide an Airtable API token to list your bases."
+    
+    result = await api_call("meta/bases")
+    
+    if "error" in result:
+        return f"Error: {result['error']}"
+    
+    bases = result.get("bases", [])
+    if not bases:
+        return "No bases found accessible with your token."
+    
+    base_list = [f"{i+1}. {base['name']} (ID: {base['id']})" for i, base in enumerate(bases)]
+    return "Available bases:\n" + "\n".join(base_list)
+
+@app.tool()
+async def list_tables(base_id_param: Optional[str] = None) -> str:
+    """List all tables in the specified base or the default base"""
+    global base_id
+    current_base = base_id_param or base_id
+    
+    if not token:
+        return "Please provide an Airtable API token to list tables."
+    
+    if not current_base:
+        return "Error: No base ID provided. Please specify a base_id or set AIRTABLE_BASE_ID environment variable."
+    
+    result = await api_call(f"meta/bases/{current_base}/tables")
+    
+    if "error" in result:
+        return f"Error: {result['error']}"
+    
+    tables = result.get("tables", [])
+    if not tables:
+        return "No tables found in this base."
+    
+    table_list = [f"{i+1}. {table['name']} (ID: {table['id']}, Fields: {len(table.get('fields', []))})" 
+                 for i, table in enumerate(tables)]
+    return "Tables in this base:\n" + "\n".join(table_list)
+
+@app.tool()
+async def list_records(table_name: str, max_records: Optional[int] = 100, filter_formula: Optional[str] = None) -> str:
+    """List records from a table with optional filtering"""
+    if not token:
+        return "Please provide an Airtable API token to list records."
+    
+    if not base_id:
+        return "Error: No base ID set. Please use --base or set AIRTABLE_BASE_ID environment variable."
+    
+    params = {"maxRecords": max_records}
+    
+    if filter_formula:
+        params["filterByFormula"] = filter_formula
+    
+    result = await api_call(f"{base_id}/{table_name}", params=params)
+    
+    if "error" in result:
+        return f"Error: {result['error']}"
+    
+    records = result.get("records", [])
+    if not records:
+        return "No records found in this table."
+    
+    # Format the records for display
+    formatted_records = []
+    for i, record in enumerate(records):
+        record_id = record.get("id", "unknown")
+        fields = record.get("fields", {})
+        field_text = ", ".join([f"{k}: {v}" for k, v in fields.items()])
+        formatted_records.append(f"{i+1}. ID: {record_id} - {field_text}")
+    
+    return "Records:\n" + "\n".join(formatted_records)
+
+@app.tool()
+async def get_record(table_name: str, record_id: str) -> str:
+    """Get a specific record from a table"""
+    if not token:
+        return "Please provide an Airtable API token to get records."
+    
+    if not base_id:
+        return "Error: No base ID set. Please set AIRTABLE_BASE_ID environment variable."
+    
+    result = await api_call(f"{base_id}/{table_name}/{record_id}")
+    
+    if "error" in result:
+        return f"Error: {result['error']}"
+    
+    fields = result.get("fields", {})
+    if not fields:
+        return f"Record {record_id} found but contains no fields."
+    
+    # Format the fields for display
+    formatted_fields = []
+    for key, value in fields.items():
+        formatted_fields.append(f"{key}: {value}")
+    
+    return f"Record ID: {record_id}\n" + "\n".join(formatted_fields)
+
+@app.tool()
+async def create_records(table_name: str, records_json: str) -> str:
+    """Create records in a table from JSON string"""
+    if not token:
+        return "Please provide an Airtable API token to create records."
+    
+    if not base_id:
+        return "Error: No base ID set. Please set AIRTABLE_BASE_ID environment variable."
+    
+    try:
+        records_data = json.loads(records_json)
+        
+        # Format the records for Airtable API
+        if not isinstance(records_data, list):
+            records_data = [records_data]
+        
+        records = [{"fields": record} for record in records_data]
+        
+        data = {"records": records}
+        result = await api_call(f"{base_id}/{table_name}", method="POST", data=data)
+        
+        if "error" in result:
+            return f"Error: {result['error']}"
+        
+        created_records = result.get("records", [])
+        return f"Successfully created {len(created_records)} records."
+        
+    except json.JSONDecodeError:
+        return "Error: Invalid JSON format in records_json parameter."
+    except Exception as e:
+        return f"Error creating records: {str(e)}"
+
+@app.tool()
+async def update_records(table_name: str, records_json: str) -> str:
+    """Update records in a table from JSON string"""
+    if not token:
+        return "Please provide an Airtable API token to update records."
+    
+    if not base_id:
+        return "Error: No base ID set. Please set AIRTABLE_BASE_ID environment variable."
+    
+    try:
+        records_data = json.loads(records_json)
+        
+        # Format the records for Airtable API
+        if not isinstance(records_data, list):
+            records_data = [records_data]
+        
+        records = []
+        for record in records_data:
+            if "id" not in record:
+                return "Error: Each record must have an 'id' field."
+            
+            rec_id = record.pop("id")
+            fields = record.get("fields", record)  # Support both {id, fields} format and direct fields
+            records.append({"id": rec_id, "fields": fields})
+        
+        data = {"records": records}
+        result = await api_call(f"{base_id}/{table_name}", method="PATCH", data=data)
+        
+        if "error" in result:
+            return f"Error: {result['error']}"
+        
+        updated_records = result.get("records", [])
+        return f"Successfully updated {len(updated_records)} records."
+        
+    except json.JSONDecodeError:
+        return "Error: Invalid JSON format in records_json parameter."
+    except Exception as e:
+        return f"Error updating records: {str(e)}"
+
+@app.tool()
+async def set_base_id(base_id_param: str) -> str:
+    """Set the current Airtable base ID"""
+    global base_id
+    base_id = base_id_param
+    return f"Base ID set to: {base_id}"
+
+if __name__ == "__main__":
+    app.run() 

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@rashidazarang/airtable-mcp",
+  "version": "1.2.0",
+  "description": "Airtable MCP for AI tools - compatible with MCP SDK 1.4.1+, includes compatibility fixes for Claude and Windsurf",
+  "main": "index.js",
+  "bin": {
+    "airtable-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "airtable",
+    "mcp",
+    "ai",
+    "claude",
+    "anthropic",
+    "cursor",
+    "claude-code",
+    "smithery",
+    "model-context-protocol",
+    "windsurf"
+  ],
+  "author": "Rashid Azarang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rashidazarang/airtable-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rashidazarang/airtable-mcp/issues"
+  },
+  "homepage": "https://github.com/rashidazarang/airtable-mcp#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "dotenv": "^16.0.3"
+  }
+}

package/publish-steps.txt

@@ -0,0 +1,27 @@
+# Steps to Publish to npm
+
+## 1. Login to npm
+```
+npm login
+```
+
+## 2. Publish the package
+```
+npm publish --access public
+```
+
+## 3. Create GitHub Release
+1. Go to https://github.com/rashidazarang/airtable-mcp/releases
+2. Click "Draft a new release"
+3. Select the tag: v1.2.0
+4. Title: "v1.2.0: Claude & Windsurf Compatibility"
+5. Copy and paste the content from RELEASE_NOTES_v1.2.0.md
+6. Attach the file: rashidazarang-airtable-mcp-1.2.0.tgz
+7. Click "Publish release"
+
+## 4. Update Smithery
+If you use Smithery, make sure to update the repository there:
+1. Login to Smithery
+2. Go to your package
+3. Update the version information
+4. Publish the update 

package/requirements.txt

@@ -0,0 +1,10 @@
+airtable-python-wrapper>=0.15.3
+anthropic>=0.19.1
+argparse>=1.4.0
+python-dotenv>=1.0.0
+pydantic>=2.4.2
+# MCP core will be installed by Smithery during deployment
+requests>=2.31.0
+typing-extensions>=4.7.1
+websockets>=11.0.3
+mcp>=1.4.1 

package/setup.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+with open("requirements.txt", "r", encoding="utf-8") as req_file:
+    requirements = req_file.read().splitlines()
+
+setup(
+    name="airtable-mcp",
+    version="1.1.0",
+    author="Rashid Azarang",
+    author_email="rashidazarang@gmail.com",
+    description="Airtable MCP for AI tools - updated to work with MCP SDK 1.4.1+",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/rashidazarang/airtable-mcp",
+    packages=find_packages(),
+    install_requires=requirements,
+    classifiers=[
+        "Programming Language :: Python :: 3.10",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.10",
+    include_package_data=True,
+) 

package/smithery.yaml

@@ -0,0 +1,41 @@
+# Smithery.ai configuration
+name: "@rashidazarang/airtable-mcp"
+version: "1.0.0"
+description: "Connect your AI tools directly to Airtable. Query, create, update, and delete records using natural language. Features include base management, table operations, schema manipulation, record filtering, and data migration—all through a standardized MCP interface compatible with Cursor, Claude Code, Cline, Zed, and other Claude-powered editors."
+
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      airtable_token:
+        type: string
+        description: "Your Airtable Personal Access Token"
+      base_id:
+        type: string
+        description: "Your default Airtable base ID (optional)"
+    required: ["airtable_token"]
+  commandFunction: |
+    (config) => {
+      // Pass config as a JSON string to the inspector_server.py
+      const configStr = JSON.stringify(config);
+      return {
+        command: "python3.10",
+        args: ["inspector_server.py", "--config", configStr],
+        env: {}
+      };
+    }
+
+listTools:
+  command: "python3.10"
+  args: ["inspector.py"]
+  env: {}
+  
+build:
+  dockerfile: "Dockerfile"
+
+metadata:
+  author: "Rashid Azarang"
+  license: "MIT"
+  repository: "https://github.com/rashidazarang/airtable-mcp"
+  homepage: "https://github.com/rashidazarang/airtable-mcp#readme" 

package/test_client.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""
+Simple test client for Airtable MCP
+"""
+import asyncio
+import json
+import sys
+import subprocess
+import time
+from typing import Dict, Any
+
+# Define the token and base ID
+TOKEN = "patnWSCSCmnsqeQ4I.2a3603372f6df67e51f9fe553012192019f2d81c3eab0f94ebd702d7fb63e338"
+BASE_ID = "appi7fWMQcB3BNzPs"
+
+# Helper function to directly make Airtable API calls
+def api_call(endpoint, token=TOKEN):
+    """Make a direct Airtable API call to test API access"""
+    import requests
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json"
+    }
+    url = f"https://api.airtable.com/v0/{endpoint}"
+    
+    try:
+        response = requests.get(url, headers=headers)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        print(f"API error: {str(e)}")
+        return {"error": str(e)}
+
+async def main():
+    # Instead of using the MCP, let's directly test the Airtable API
+    print("Testing direct API access...")
+    
+    # List bases
+    print("\nListing bases:")
+    result = api_call("meta/bases")
+    if "error" in result:
+        print(f"Error: {result['error']}")
+    else:
+        bases = result.get("bases", [])
+        for i, base in enumerate(bases):
+            print(f"{i+1}. {base['name']} (ID: {base['id']})")
+    
+    # List tables in the specified base
+    print(f"\nListing tables in base {BASE_ID}:")
+    result = api_call(f"meta/bases/{BASE_ID}/tables")
+    if "error" in result:
+        print(f"Error: {result['error']}")
+    else:
+        tables = result.get("tables", [])
+        for i, table in enumerate(tables):
+            print(f"{i+1}. {table['name']} (ID: {table['id']}, Fields: {len(table.get('fields', []))})")
+            # Print fields
+            print("   Fields:")
+            for field in table.get('fields', []):
+                print(f"   - {field['name']} ({field['type']})")
+
+if __name__ == "__main__":
+    asyncio.run(main())