sdhector/mcp-automr

AutoMR MCP Server - Digital Questionnaire System

A comprehensive Model Context Protocol (MCP) server that provides Claude.ai with powerful tools to create, manage, and analyze digital questionnaires (surveys, forms, feedback collection) using Google Forms, Sheets, and Drive APIs. Built with FastMCP and designed for both local and Cloud Run deployment.

Features

• 🚀 FastMCP-based - Uses the official MCP SDK with proper SSE transport
• 📋 Complete Questionnaire Management - Create, read, update, and delete questionnaires
• 🤖 Intelligent Question Detection - Automatically detects question types from natural language
• 📊 Response Analytics - Get summary statistics, detailed responses, or raw data
• 🔐 Secure OAuth 2.0 - Google OAuth authentication with proper credential management
• ☁️ Cloud Run Ready - Optimized for serverless deployment
• 📝 JSON Logging - Structured logs for debugging

Quick Start

Prerequisites

• Python 3.9+
• Google Cloud Project with APIs enabled (Forms, Sheets, Drive)
• OAuth 2.0 credentials from Google Cloud Console
• See for detailed setup instructions

Local Setup

1. Clone and navigate to the repository:

   cd mcp-automr
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up Google OAuth credentials:

   • Follow the guide in
   • Download your credentials.json file to the project root
   • The first time you use the tools, a browser will open for authentication

4. Run the server locally:

   export PORT=8080
   uvicorn main:app --host 0.0.0.0 --port 8080
   

5. Test the server:

   curl http://localhost:8080/health
   

Cloud Run Deployment

1. Deploy to Cloud Run:

   ./deploy.sh
   # or on Windows:
   .\deploy.ps1
   

2. Add to Claude.ai:

   • Go to Claude.ai Settings > Integrations
   • Click 'Add remote MCP server'
   • Enter URL: https://YOUR-SERVICE-URL.run.app/sse/sse

Note: For Cloud Run, you'll need to handle authentication differently as the OAuth flow requires browser interaction. Consider using service accounts or pre-authenticated tokens.

Architecture

┌─────────────┐    HTTPS/SSE     ┌──────────────────────┐
│  Claude.ai  │ ──────────────> │  MCP Server          │
│             │    /sse/sse      │  (main.py)           │
│             │                  │   FastMCP +          │
│             │                  │   Starlette          │
└─────────────┘                  └──────────────────────┘
                                          │
                                          ├─> Google Forms API
                                          ├─> Google Sheets API
                                          └─> Google Drive API

Key Components:

• main.py - FastMCP server with MCP tool definitions
• src/mcp_automr/google_apis.py - OAuth 2.0 authentication and service initialization
• src/mcp_automr/questionnaire_service.py - Core questionnaire business logic
• deploy.sh / deploy.ps1 - Automated deployment scripts
• Dockerfile - Container configuration

Available Tools

📋 Questionnaire Management Tools

1. create_questionnaire

Create a complete questionnaire with intelligent question type detection.

Parameters:

• title (required): Questionnaire title
• questions (required): List of question dictionaries
  • text (required): Question text
  • type (optional): Question type (auto-detected if not specified)
  • options (optional): List of choices for multiple-choice questions
  • required (optional): Whether answer is mandatory
  • scale_min / scale_max (optional): For scale questions
  • scale_min_label / scale_max_label (optional): Scale labels
  • allow_multiple (optional): For checkbox questions
• description (optional): Questionnaire description
• collect_responses (optional): Whether to set up response collection

Example:

create_questionnaire(
    title="Customer Satisfaction Survey",
    description="Help us improve our service",
    questions=[
        {"text": "How satisfied are you?", "type": "scale", "scale_min": 1, "scale_max": 5},
        {"text": "What did you like?", "type": "long_text"},
        {"text": "Would you recommend us?", "options": ["Yes", "No", "Maybe"]}
    ]
)

Intelligent Question Type Detection:

• Detects email questions by keyword
• Auto-detects multiple choice, checkboxes, dropdowns from options
• Identifies scale questions from range parameters
• Recognizes date/time questions from keywords
• Distinguishes short vs long text based on context

2. get_questionnaire_responses

Retrieve and analyze responses from a questionnaire.

Parameters:

• questionnaire_id (required): ID from create_questionnaire or list_questionnaires
• format (optional): "summary", "detailed", or "raw" (default: "summary")
• filters (optional): Response filters (date range, completion, etc.)

Formats:

• summary: Aggregated statistics, response count, completion rate
• detailed: All individual responses with timestamps
• raw: Unprocessed data for export

Example:

get_questionnaire_responses(
    questionnaire_id="abc123xyz",
    format="summary"
)

3. list_questionnaires

List all questionnaires the user has access to.

Parameters:

• limit (optional): Maximum number to return (default: 20)
• filter (optional): Filter by title substring
• sort_by (optional): "created_date", "modified_date", or "title"
• include_archived (optional): Include trashed questionnaires

Example:

list_questionnaires(
    limit=10,
    filter="customer",
    sort_by="modified_date"
)

4. update_questionnaire

Modify an existing questionnaire.

Parameters:

• questionnaire_id (required): ID of questionnaire to update
• updates (required): Dictionary of changes:
  • title: New title
  • description: New description
  • add_questions: List of questions to add
  • remove_questions: List of question indices to remove
  • edit_questions: List of question edits
  • settings: Form settings (accept responses, etc.)

Example:

update_questionnaire(
    questionnaire_id="abc123xyz",
    updates={
        "title": "Updated Survey Title",
        "add_questions": [{"text": "New question?", "type": "short_text"}],
        "remove_questions": [2]
    }
)

5. delete_questionnaire

Delete or archive a questionnaire.

Parameters:

• questionnaire_id (required): ID of questionnaire to delete
• mode (optional): "archive" or "permanent" (default: "archive")
• confirm_permanent (optional): Must be True for permanent deletion

Example:

# Archive (safe, recoverable)
delete_questionnaire(questionnaire_id="abc123xyz", mode="archive")

# Permanent deletion
delete_questionnaire(
    questionnaire_id="abc123xyz",
    mode="permanent",
    confirm_permanent=True
)

🌍 Testing Tools

hello_world

Simple greeting tool for testing the MCP connection.

Parameters: name (optional, default: "World")

Example: hello_world(name="Claude")

Development

Local Testing

# Install dependencies
pip install -r requirements.txt

# Set up Google credentials (see SETUP_GOOGLE_AUTH.md)
# Place credentials.json in project root

# Set environment variables
export PORT=8080

# Run server
uvicorn main:app --host 0.0.0.0 --port 8080

# In another terminal, test the health endpoint
curl http://localhost:8080/health

# View the web interface
open http://localhost:8080

Project Structure

mcp-automr/
├── main.py                               # FastMCP server with MCP tool definitions
├── src/
│   └── mcp_automr/
│       ├── __init__.py                   # Package initialization
│       ├── google_apis.py                # OAuth 2.0 and Google API services
│       └── questionnaire_service.py      # Core questionnaire business logic
├── requirements.txt                      # Python dependencies
├── credentials.json                      # OAuth 2.0 credentials (not in git)
├── credentials.json.example              # Template for credentials
├── token.pickle                          # Cached OAuth token (not in git)
├── SETUP_GOOGLE_AUTH.md                  # Authentication setup guide
├── Dockerfile                            # Container definition
├── deploy.sh / deploy.ps1                # Deployment automation
├── .gitignore                            # Git ignore rules
└── README.md                             # This file

Extending the Server

The questionnaire system is designed to be extensible. To add more functionality:

Adding New Tools

1. Add business logic to src/mcp_automr/questionnaire_service.py:

def new_feature(param: str) -> dict[str, Any]:
    """Implement your feature logic here."""
    forms_service = get_forms_service()
    # Your implementation
    return {"success": True, "data": result}

2. Define the MCP tool in main.py:

@mcp.tool()
def new_tool(param: str) -> str:
    """
    Tool description for Claude.

    Args:
        param: Parameter description

    Returns:
        JSON result
    """
    result = new_feature(param)
    return json.dumps(result, indent=2)

Working with Google APIs

The system uses three Google APIs:

• Forms API: Create and manage forms
• Sheets API: Read response data
• Drive API: List, organize, and delete files

All services are accessed through google_apis.py:

from src.mcp_automr.google_apis import (
    get_forms_service,
    get_sheets_service,
    get_drive_service
)

forms_service = get_forms_service()
sheets_service = get_sheets_service()
drive_service = get_drive_service()

Usage Examples

Natural Language Commands with Claude

Once connected to Claude.ai, you can use natural language to interact with the questionnaire system:

Create a survey:

"Create a customer satisfaction survey with 5 questions about product quality, delivery speed, customer service, price, and overall satisfaction."

Get responses:

"Show me the responses from my customer satisfaction survey with summary statistics."

List surveys:

"List all my surveys from the last month."

Update a survey:

"Add a question about product recommendations to my customer satisfaction survey."

Delete a survey:

"Archive my old test survey."

Direct API Usage

You can also use the MCP tools directly through the server:

# Example: Create a simple feedback form
create_questionnaire(
    title="Quick Feedback",
    description="We'd love to hear from you!",
    questions=[
        {
            "text": "How would you rate your experience?",
            "type": "scale",
            "scale_min": 1,
            "scale_max": 10,
            "scale_min_label": "Poor",
            "scale_max_label": "Excellent",
            "required": True
        },
        {
            "text": "What could we improve?",
            "type": "long_text"
        },
        {
            "text": "Would you recommend us to a friend?",
            "options": ["Definitely", "Probably", "Not sure", "Probably not", "Definitely not"],
            "required": True
        }
    ]
)

Troubleshooting

Google Authentication Issues

See for detailed authentication troubleshooting.

Common issues:

• credentials.json not found: Place the file in the project root
• Access blocked: Configure OAuth consent screen and add test users
• Token expired: Delete token.pickle and re-authenticate

API Errors

Quota exceeded:

{
  "success": false,
  "error": "api_error",
  "message": "Quota exceeded. Please try again later."
}

Solution: Wait for quota reset (daily) or request higher quota in Google Cloud Console.

Permission denied:

{
  "success": false,
  "error": "api_error",
  "message": "Insufficient permissions"
}

Solution: Verify all required APIs are enabled and OAuth scopes are correct.

Server Health Check

# Local
curl http://localhost:8080/health

# Cloud Run
curl https://YOUR-SERVICE-URL.run.app/health

View Logs

# Cloud Run logs
gcloud logging read 'resource.type=cloud_run_revision AND resource.labels.service_name=automr-mcp' --limit=50

# Local logs (stdout)
# Logs are in JSON format for structured analysis

Important Notes

Response Collection Limitation

Google Forms API does not support programmatically linking forms to response sheets. After creating a questionnaire, you need to manually:

1. Open the form edit URL
2. Click the "Responses" tab
3. Click the Google Sheets icon to create a linked sheet

This is a one-time setup per questionnaire. Once linked, the get_questionnaire_responses tool can read responses directly from the Forms API.

API Quotas

Google APIs have daily quotas (free tier):

• Forms API: 300 requests/minute
• Sheets API: 100 requests/100 seconds
• Drive API: 1,000 requests/100 seconds

These are sufficient for normal use. The server implements error handling for quota limits.

Security

• Never commit credentials.json or token.pickle to version control
• Keep OAuth credentials secure
• Use service accounts for production deployments
• Review API access in Google Account Security

License

MIT

Contributing

Contributions welcome! Please ensure:

• All tools follow the FastMCP decorator pattern
• Include proper type hints and docstrings
• Add error handling for API failures
• Update documentation for new features
• Follow the existing code structure

Version

Current Version: 0.2.0

v0.2.0 (Current)

• ✨ Complete questionnaire system with 5 MCP tools
• 🔐 OAuth 2.0 authentication for Google APIs
• 🤖 Intelligent question type detection
• 📊 Response analytics (summary, detailed, raw formats)
• 📋 Full CRUD operations for questionnaires
• 📚 Comprehensive documentation and setup guides

v0.1.0

• Initial release with hello_world tool
• FastMCP-based architecture with SSE transport
• Cloud Run optimized deployment

Support

For issues or questions:

• Google API authentication: See
• MCP Server issues: Check server logs and verify credentials
• Feature requests: Open an issue on GitHub

Roadmap

Future enhancements:

• Automated response sheet linking (requires Apps Script)
• Response filtering by date range and criteria
• Export responses to CSV/Excel
• Form templating system
• Batch operations for multiple questionnaires
• Service account support for Cloud Run
• Webhook notifications for new responses
• Advanced analytics and visualizations