{"id":30523009,"url":"https://github.com/rashidazarang/airtable-ai-agent","last_synced_at":"2026-05-16T17:39:37.730Z","repository":{"id":310035671,"uuid":"1038461070","full_name":"rashidazarang/airtable-ai-agent","owner":"rashidazarang","description":"🤖 The most comprehensive AI Agent for Airtable operations - Natural language interface with 33 MCP tools, complete API knowledge, and production-ready deployment","archived":false,"fork":false,"pushed_at":"2025-09-09T20:39:25.000Z","size":80,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-09T18:37:01.254Z","etag":null,"topics":["ai-agents","airtable","airtable-api","artificial-intelligence","claude","claude-code","nlp","server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rashidazarang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T08:36:37.000Z","updated_at":"2025-10-09T03:34:22.000Z","dependencies_parsed_at":"2025-08-15T10:28:07.115Z","dependency_job_id":"5bff7430-cf2c-4438-92c4-7a9f0d2c0534","html_url":"https://github.com/rashidazarang/airtable-ai-agent","commit_stats":null,"previous_names":["rashidazarang/airtable-ai-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rashidazarang/airtable-ai-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashidazarang%2Fairtable-ai-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashidazarang%2Fairtable-ai-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashidazarang%2Fairtable-ai-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashidazarang%2Fairtable-ai-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rashidazarang","download_url":"https://codeload.github.com/rashidazarang/airtable-ai-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashidazarang%2Fairtable-ai-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33112372,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","airtable","airtable-api","artificial-intelligence","claude","claude-code","nlp","server"],"created_at":"2025-08-26T19:44:30.310Z","updated_at":"2026-05-16T17:39:37.697Z","avatar_url":"https://github.com/rashidazarang.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Airtable AI Agent\n\n\u003e **The most comprehensive AI Agent for Airtable operations**\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Tests](https://github.com/rashidazarang/airtable-ai-agent/workflows/Tests/badge.svg)](https://github.com/rashidazarang/airtable-ai-agent/actions)\n[![Coverage](https://img.shields.io/codecov/c/github/rashidazarang/airtable-ai-agent)](https://codecov.io/gh/rashidazarang/airtable-ai-agent)\n\n## 🌟 What Makes This Special?\n\nThis AI Agent represents the **pinnacle of Airtable automation**, combining:\n\n- 🧠 **Complete Airtable API Knowledge** - Every endpoint, every parameter, every best practice\n- 🔗 **Perfect MCP Integration** - Seamless connection to our comprehensive 33-tool MCP server (v3.2.4)  \n- 🚀 **Advanced NLP** - Understand complex natural language queries about Airtable\n- ⚡ **Intelligent Context Management** - Optimal performance with 128k context window\n- 🎯 **Production Ready** - Docker, CI/CD, monitoring, security built-in\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TB\n    User[User Query] --\u003e Agent[AI Agent Core]\n    Agent --\u003e Expert[Airtable Expert]\n    Agent --\u003e Context[Context Manager]\n    Agent --\u003e MCP[MCP Client]\n    \n    Expert --\u003e Analysis[Query Analysis]\n    Expert --\u003e Planning[Operation Planning]\n    Expert --\u003e Response[Response Generation]\n    \n    Context --\u003e Docs[Documentation Store]\n    Context --\u003e Embeddings[Semantic Search]\n    Context --\u003e Cache[Intelligent Cache]\n    \n    MCP --\u003e Server[MCP Server]\n    Server --\u003e Airtable[Airtable API]\n    \n    style Agent fill:#e1f5fe\n    style Expert fill:#f3e5f5\n    style Context fill:#e8f5e8\n    style MCP fill:#fff3e0\n```\n\n## 🚀 Quick Start\n\n### Option 1: Docker (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/rashidazarang/airtable-ai-agent.git\ncd airtable-ai-agent/ai-agent\n\n# Set environment variables\nexport AIRTABLE_TOKEN=\"your_personal_access_token\"\nexport AIRTABLE_BASE_ID=\"your_airtable_base_id\"\n\n# Start with Docker Compose (includes MCP server, Redis, monitoring)\ndocker-compose up -d\n\n# Test the agent\ncurl -X POST http://localhost:8000/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"List all tables in my base\"}'\n```\n\n### Option 2: Local Development\n\n```bash\n# Create virtual environment\npython3.11 -m venv venv\nsource venv/bin/activate\n\n# Install dependencies  \npip install -r requirements.txt\n\n# Install and start MCP server v3.2.4 (in separate terminal)\nnpm install -g @rashidazarang/airtable-mcp@3.2.4\nAIRTABLE_TOKEN=\"your_token\" AIRTABLE_BASE_ID=\"your_base\" npx @rashidazarang/airtable-mcp\n\n# Run the agent\ncd ai-agent\npython -m src.agent\n```\n\n## 💬 Usage Examples\n\n### Interactive Mode\n\n```python\nfrom src.agent import AirtableAIAgent\n\nagent = AirtableAIAgent()\nawait agent.initialize()\n\n# Natural language queries\nresponse = await agent.process_query(\"Show me all active projects with high priority\")\nresponse = await agent.process_query(\"Create a new task called 'Review documentation'\")  \nresponse = await agent.process_query(\"Update all completed tasks to archive status\")\nresponse = await agent.process_query(\"Set up a webhook for when new records are added\")\n```\n\n### HTTP API\n\n```bash\n# Start the agent server\npython -m src.agent --server\n\n# Make requests\ncurl -X POST http://localhost:8000/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"Create a project tracking table with Name, Status, Priority, and Due Date fields\",\n    \"context\": {\"previous_operations\": []}\n  }'\n```\n\n### Batch Processing\n\n```python\nqueries = [\n    \"List all tables in my base\",\n    \"Show me the schema for the Tasks table\", \n    \"Create 5 sample records in the Tasks table\",\n    \"Set up webhooks for real-time notifications\"\n]\n\nresponses = await agent.batch_process(queries)\n```\n\n## 🎯 Core Features\n\n### 🧠 Advanced Query Understanding\n\n- **Intent Recognition** - Automatically detects what you want to do\n- **Entity Extraction** - Finds table names, field names, record IDs\n- **Context Awareness** - Remembers previous operations and preferences\n- **Complexity Analysis** - Breaks down complex requests into steps\n\n### 🔗 Comprehensive MCP Integration\n\nDirect integration with our **33-tool Airtable MCP server**:\n\n#### Data Operations (7 tools)\n- `list_tables`, `list_records`, `get_record`\n- `create_record`, `update_record`, `delete_record`  \n- `search_records`\n\n#### Webhook Management (5 tools)\n- `list_webhooks`, `create_webhook`, `delete_webhook`\n- `get_webhook_payloads`, `refresh_webhook`\n\n#### Schema Discovery (5 tools)  \n- `list_bases`, `get_base_schema`, `describe_table`\n- `list_field_types`, `get_table_views`\n\n#### Table Management (3 tools)\n- `create_table`, `update_table`, `delete_table`\n\n#### Field Management (3 tools)\n- `create_field`, `update_field`, `delete_field`\n\n#### Batch Operations (4 tools)\n- `batch_create_records`, `batch_update_records`\n- `batch_delete_records`, `batch_upsert_records`\n\n#### Advanced Features (6 tools)\n- `upload_attachment`, `create_view`, `get_view_metadata`\n- `create_base`, `list_collaborators`, `list_shares`\n\n### 📚 Complete Knowledge Base\n\nThe agent has **complete Airtable documentation** in its context:\n\n- **Web API Reference** - Every endpoint, parameter, response format\n- **JavaScript SDK** - Complete Airtable.js documentation and examples\n- **Formulas Guide** - All functions, operators, and patterns\n- **Apps \u0026 Extensions** - SDK documentation and integration patterns  \n- **MCP Tools** - Our comprehensive tool documentation\n\n### ⚡ Performance Optimization\n\n- **Intelligent Context Management** - Semantic search through documentation\n- **Token Optimization** - Fits maximum relevant context in 128k window\n- **Parallel Processing** - Concurrent MCP operations where safe\n- **Smart Caching** - Embeddings, API responses, and context chunks\n- **Batch Operations** - Automatic batching for efficiency\n\n## 🔧 Configuration\n\n### Agent Configuration (`config/agent_config.yaml`)\n\n```yaml\nname: \"Airtable AI Agent\"\nversion: \"1.0.0\"\nmax_context_tokens: 128000\nmcp_server_url: \"http://localhost:8010/mcp\"\nlog_level: \"INFO\"\nenable_metrics: true\ncache_duration: 300\n\n# Context management\ncontext:\n  max_chunks_per_query: 10\n  relevance_threshold: 0.7\n  enable_semantic_search: true\n\n# Performance\nperformance:\n  max_concurrent_operations: 5\n  request_timeout: 30\n  retry_attempts: 3\n```\n\n### Environment Variables\n\n```bash\n# Required\nAIRTABLE_TOKEN=your_personal_access_token\nAIRTABLE_BASE_ID=your_base_id\n\n# Optional\nMCP_SERVER_URL=http://localhost:8010/mcp\nLOG_LEVEL=INFO\nREDIS_URL=redis://localhost:6379\nPOSTGRES_URL=postgresql://user:pass@localhost/aiagent\n```\n\n## 🚀 Deployment\n\n### Production Docker Deployment\n\n```yaml\n# docker-compose.prod.yml\nversion: '3.8'\nservices:\n  airtable-ai-agent:\n    image: ghcr.io/rashidazarang/airtable-ai-agent:latest\n    ports:\n      - \"8000:8000\"\n    environment:\n      - LOG_LEVEL=INFO\n      - MCP_SERVER_URL=http://airtable-mcp:8010/mcp\n    volumes:\n      - ./data:/app/data\n      - ./logs:/app/logs\n    restart: unless-stopped\n    \n  # Includes: MCP server, Redis, PostgreSQL, Prometheus, Grafana, Nginx\n```\n\n### Kubernetes Deployment\n\n```yaml\n# k8s/deployment.yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: airtable-ai-agent\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: airtable-ai-agent\n  template:\n    metadata:\n      labels:\n        app: airtable-ai-agent\n    spec:\n      containers:\n      - name: ai-agent\n        image: ghcr.io/rashidazarang/airtable-ai-agent:latest\n        ports:\n        - containerPort: 8000\n        env:\n        - name: AIRTABLE_TOKEN\n          valueFrom:\n            secretKeyRef:\n              name: airtable-secrets\n              key: token\n```\n\n## 📊 Monitoring \u0026 Observability\n\n### Built-in Metrics\n\n- **Request metrics** - Response times, success rates, error rates\n- **MCP operations** - Tool usage, performance, success rates  \n- **Context usage** - Token utilization, cache hit rates\n- **Performance** - Memory usage, concurrent operations\n\n### Prometheus Metrics\n\n```\n# Performance metrics\nairtable_agent_requests_total\nairtable_agent_request_duration_seconds\nairtable_agent_mcp_operations_total\nairtable_agent_context_tokens_used\nairtable_agent_cache_hit_ratio\n\n# Business metrics  \nairtable_agent_queries_by_intent\nairtable_agent_operations_by_type\nairtable_agent_user_satisfaction_score\n```\n\n### Grafana Dashboard\n\nPre-built dashboard includes:\n- **Request volume and latency**\n- **MCP operation success rates** \n- **Context utilization metrics**\n- **Error tracking and analysis**\n- **User intent distribution**\n\n## 🧪 Testing\n\n### Run Tests\n\n```bash\n# Unit tests\npytest tests/test_agent.py -v\n\n# Integration tests  \npytest tests/test_integration.py -v\n\n# Performance tests\npytest tests/test_performance.py -v\n\n# All tests with coverage\npytest --cov=src --cov-report=html\n```\n\n### Test Categories\n\n- **Unit Tests** - Individual component testing\n- **Integration Tests** - MCP server integration\n- **Performance Tests** - Load testing, memory usage\n- **End-to-End Tests** - Complete workflow validation\n\n## 📈 Performance Benchmarks\n\n| Metric | Value |\n|--------|--------|  \n| **Query Response Time** | \u003c 2 seconds (95th percentile) |\n| **Context Processing** | \u003c 500ms for 10 chunks |\n| **MCP Operations** | \u003c 1 second per operation |\n| **Concurrent Queries** | 100+ simultaneous users |\n| **Memory Usage** | \u003c 512MB per instance |\n| **Cache Hit Rate** | \u003e 80% for repeated queries |\n\n## 🔒 Security\n\n### Built-in Security Features\n\n- **Token Security** - Secure token storage and rotation\n- **Input Validation** - All inputs sanitized and validated  \n- **Rate Limiting** - Protection against abuse\n- **Audit Logging** - Complete operation audit trail\n- **Error Sanitization** - No sensitive data in error messages\n\n### Security Best Practices\n\n```python\n# Example secure configuration\nsecurity = {\n    \"token_rotation_days\": 30,\n    \"max_requests_per_minute\": 100,\n    \"enable_audit_logging\": True,\n    \"sanitize_error_messages\": True,\n    \"require_https\": True\n}\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository**\n2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Make your changes** with tests\n4. **Run the test suite** (`pytest`)  \n5. **Submit a pull request**\n\n### Development Setup\n\n```bash\n# Clone your fork\ngit clone https://github.com/your-username/airtable-ai-agent.git\ncd airtable-ai-agent/ai-agent\n\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n```\n\n## 📋 Roadmap\n\n### Version 1.1 (Next Release)\n- [ ] **Multi-base Support** - Work across multiple Airtable bases\n- [ ] **Custom Integrations** - Plugin system for external services\n- [ ] **Advanced Analytics** - Built-in data analysis capabilities\n- [ ] **Voice Interface** - Voice commands and responses\n\n### Version 1.2 (Future)  \n- [ ] **Machine Learning** - Predictive suggestions and automation\n- [ ] **Workflow Builder** - Visual workflow designer\n- [ ] **Mobile App** - Native iOS/Android applications\n- [ ] **Enterprise SSO** - SAML, OAuth, Active Directory support\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙋‍♂️ Support\n\n### Getting Help\n\n- **Documentation**: Complete documentation in this repository\n- **GitHub Issues**: [Report bugs or request features](https://github.com/rashidazarang/airtable-ai-agent/issues)\n- **Discussions**: [Community discussions](https://github.com/rashidazarang/airtable-ai-agent/discussions)\n\n### Commercial Support\n\nFor enterprise deployments and commercial support:\n- **GitHub Issues**: Technical support through GitHub issues\n- **Contributions**: Pull requests welcome!\n\n## ⭐ Star History\n\nIf this project helps you, please consider giving it a star!\n\n[![Star History Chart](https://api.star-history.com/svg?repos=rashidazarang/airtable-ai-agent\u0026type=Date)](https://star-history.com/#rashidazarang/airtable-ai-agent)\n\n---\n\n**Built with ❤️ for the Airtable community**\n\n*Making Airtable automation accessible to everyone through the power of AI.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frashidazarang%2Fairtable-ai-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frashidazarang%2Fairtable-ai-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frashidazarang%2Fairtable-ai-agent/lists"}