MCP Server for AI Integration
A comprehensive Model Context Protocol (MCP) server built with FastMCP 2.0 that provides AI agents with access to a powerful suite of tools and services. This modular, extensible server enables seamless integration with various platforms, APIs, and automation workflows.
🚀 Overview
The Model Context Protocol (MCP) allows AI agents to interact with external tools and services through a standardized interface. This implementation provides a rich toolkit that enables AI agents to:
- 🔍 Search & Research: Web search, local business discovery, and content extraction
- 🌤️ Real-time Data: Weather information and forecasts worldwide
- 🧮 Calculations: Mathematical operations with error handling
- 📂 File System Access: Read and explore local files and directories
- 🕷️ Web Automation: Browser control and website content extraction
- 📊 Data Management: Airtable database operations and structured data handling
- 📝 Document Creation: Google Workspace integration (Sheets, Docs, Slides)
- 🔗 Platform Integration: Ready for n8n, Claude Desktop, and custom applications
✨ Key Features
- Brave Search Integration: Web search, news, videos, and local business discovery
- Real-time Weather: Current conditions and forecasts using Open-Meteo API
- Web Crawling: Extract content from websites using Crawl4AI with structured data support
- Browser Automation: Full browser control with Playwright for interactive web tasks
📊 Data & Productivity
- File System Access: Read local files, explore directories, search content with secure read-only access
- Airtable Management: Create bases, manage tables, search records with template library
- Google Sheets: Create spreadsheets, manipulate data, collaborative editing
- Google Docs: Document creation, content editing, and collaborative writing
- Google Slides: Presentation creation, slide management, template-based workflows
- Calculator: Reliable arithmetic operations with comprehensive error handling
🏗️ Architecture Highlights
- FastMCP 2.0: Built on the latest MCP framework for optimal performance
- Modular Design: Tools in separate modules for easy management and extension
- Session Context: Smart memory for recent operations and created documents
- SSE Support: Server-Sent Events for real-time communication
- Flexible Authentication: OAuth2, Bearer tokens, and API key support
- Error Resilience: Comprehensive error handling with graceful degradation
🚀 Quick Start
1. Installation
# Clone the repository
git clone <repository-url>
cd mcp-server
# Install with uv (recommended)
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
# Or with pip
pip install -r requirements.txt
2. Environment Setup
Create a .env file in the project root:
# Server Configuration
MCP_SERVER_NAME=my-mcp-server
MCP_HOST=0.0.0.0
MCP_PORT=8000
# Required API Keys
BRAVE_API_KEY=your_brave_search_api_key
AIRTABLE_PERSONAL_ACCESS_TOKEN=your_airtable_token
# Optional: Google Workspace (for Sheets, Docs, Slides)
GOOGLE_CREDENTIALS_FILE=credentials.json
GOOGLE_TOKEN_FILE=token.json
3. Optional Dependencies
For enhanced functionality, install additional tools:
# Web crawling and browser automation
pip install crawl4ai playwright
playwright install
# Google Workspace integration
pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client
4. Launch the Server
Your server will be available at:
- Base URL:
http://localhost:8000 - SSE Endpoint:
http://localhost:8000/sse - MCP Protocol: Ready for AI agent connections
| Category | Tools | API Required | Status |
|---|
| Search & Web | 2 web search tools | Brave API | ✅ Core |
| Weather | Global weather data | None (Open-Meteo) | ✅ Core |
| Calculator | Arithmetic operations | None | ✅ Core |
| File System | 5 file/directory tools | None | ✅ Core |
| Web Automation | 3 crawling + 10 browser tools | None (local) | ⚡ Optional |
| Airtable | 15+ database tools | Airtable Token | ✅ Core |
| Google Sheets | 8 spreadsheet tools | Google OAuth2 | ⚡ Optional |
| Google Docs | 5 document tools | Google OAuth2 | ⚡ Optional |
| Google Slides | 10 presentation tools | Google OAuth2 | ⚡ Optional |
brave_web_search, brave_local_search - Web and local business searchget_weather - Current weather and forecasts for any locationcalculator - Basic arithmetic with error handlingget_system_info, read_file, list_directory - File system explorationcreate_airtable_base, list_records, etc. - Database management
Smart Context Features
- Session Memory: Tracks recently created documents and spreadsheets
- Title Search: Find documents by name without IDs
- Auto-append: Add to most recent spreadsheet/document
- Template Library: Pre-built Airtable templates (CRM, project management, etc.)
- File System Navigation: Supports
~ for home directory, cross-platform paths
🔌 Integration Examples
n8n Workflow Integration
- Add MCP Client Tool node to your workflow
- Configure the SSE endpoint:
http://your-server:8000/sse - Select which tools to expose to your AI agent
- Configure authentication if required
{
"endpoint": "http://localhost:8000/sse",
"authentication": "bearer",
"tools": ["brave_web_search", "get_weather", "read_file", "create_google_sheet"]
}
Claude Desktop Integration
Add to your Claude Desktop configuration:
{
"mcpServers": {
"enhanced-mcp-server": {
"command": "python",
"args": ["/absolute/path/to/run.py"],
"env": {
"BRAVE_API_KEY": "your_brave_api_key",
"AIRTABLE_PERSONAL_ACCESS_TOKEN": "your_airtable_token"
}
}
}
}
Custom Application
Connect via HTTP API with JSON responses:
import httpx
async def call_mcp_tool():
async with httpx.AsyncClient() as client:
response = await client.post(
"http://localhost:8000/messages",
json={
"tool": "list_directory",
"parameters": {"directory_path": "~"}
}
)
return response.json()
📊 Advanced Features
File System Integration
Secure, read-only access to local files:
- Cross-Platform: Works on Windows, Linux, and macOS
- Smart Path Handling: Supports
~ for home directory and environment variables - Content Search: Find files by name patterns or content
- Size Controls: Configurable limits prevent memory issues
- Permission Aware: Respects file system permissions
Airtable Template System
Create production-ready bases instantly:
- CRM: Customer relationship management with deals pipeline
- Project Management: Tasks, projects, and team coordination
- Inventory: Product tracking with stock levels and suppliers
- Event Planning: Event management with task coordination
- Content Calendar: Content planning and publishing workflow
Google Workspace Integration
Seamless document creation and management:
- Context-Aware: Automatically tracks recent creations
- Smart Operations: "Append to last sheet", "Edit recent doc"
- Collaborative: Built-in sharing and permission management
- Template Support: Copy from existing documents and presentations
Web Automation Capabilities
Powerful browser control for complex tasks:
- Multi-Browser: Chrome, Firefox, Safari support
- Session Management: Multiple concurrent browser contexts
- Interaction Suite: Click, fill forms, wait for elements, execute JavaScript
- Content Extraction: Screenshots, accessibility trees, structured data
🔧 Development & Extension
- Create a new tool file in
tools/:
# tools/my_tool.py
from typing import Dict, Any
async def my_function(param: str) -> Dict[str, Any]:
"""Tool description for AI agents."""
try:
result = f"Processed: {param}"
return {"result": result, "status": "success"}
except Exception as e:
return {"error": str(e), "status": "error"}
def register(mcp_instance):
mcp_instance.tool()(my_function)
- Import and register in
run.py:
from tools import my_tool
my_tool.register(mcp)
Development Setup
# Install development dependencies
uv pip install pytest python-dotenv
# Run tests
pytest tests/
# Test specific tools
python -m tests.test_mcp_crawler
🔐 API Setup & Costs
Required for Full Functionality
Brave Search API (Get API Key)
- Free tier: 2,000 queries/month
- Paid plans: Higher limits available
- Usage: Web search and local business discovery
Airtable Personal Access Token (Generate Token)
- Free tier: Generous usage limits
- Usage: Database creation and management
Google Workspace APIs (Setup Guide)
- Free tier with setup required
- OAuth2 credentials needed
- Usage: Sheets, Docs, and Slides integration
Free Services
- Weather: Open-Meteo API (unlimited)
- Calculator: Built-in functionality
- File System: Local file access (no external dependencies)
- Web Crawling: Local browser automation
- Browser Control: Local Playwright execution
📖 Documentation
🚀 Production Deployment
Docker Deployment (Example)
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
# Install optional dependencies
RUN pip install crawl4ai playwright && playwright install --with-deps
EXPOSE 8000
CMD ["python", "run.py"]
Environment Variables
# Production settings
MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_SERVER_NAME=production-mcp-server
# Secure token management
BRAVE_API_KEY=${BRAVE_API_KEY}
AIRTABLE_PERSONAL_ACCESS_TOKEN=${AIRTABLE_TOKEN}
🛡️ Security & Best Practices
API Key Security
- Store keys in environment variables, never in code
- Use different keys for development and production environments
- Monitor API usage and set up alerts for unusual activity
- Rotate keys regularly and update access
File System Security
- Read-only access prevents accidental system modification
- File size limits (50MB default) prevent memory exhaustion
- Path validation prevents directory traversal attacks
- Permission respect maintains existing security boundaries
- Use tool selection in n8n to limit available functions
- Monitor tool usage through logging
- Implement rate limiting for production deployments
- Review and audit tool access regularly
🤝 Contributing
We welcome contributions! Please:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-tool - Add tests for new functionality
- Ensure all tests pass:
pytest - Submit a pull request
Areas for Contribution
- New tool integrations (Slack, GitHub, etc.)
- Enhanced error handling and logging
- Performance optimizations
- Documentation improvements
- Testing and quality assurance
📞 Support & Community
- Issues: Report bugs and request features via GitHub Issues
- Documentation: Complete tool docs in the
docs/ directory - Examples: Usage examples and workflows in
examples/ directory
🏆 Built With
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Ready to supercharge your AI workflows? Get started with the installation guide above and explore the comprehensive tool documentation to unlock the full potential of your AI agents.