Method CRM MCP Server

A production-ready Model Context Protocol (MCP) server for Method CRM API integration. This server enables LLMs to interact with Method CRM data through well-designed tools for tables, files, users, events, and API key management.

Features

• 20 Comprehensive Tools covering all Method CRM operations
• API Key Authentication (fully implemented) with OAuth2 placeholders
• Dual Transport Support: stdio (local) and streamable HTTP (remote)
• Rate Limiting & Retry Logic: Automatic handling of API limits
• Type-Safe: Full Pydantic validation for all inputs
• Actionable Errors: Clear error messages with suggestions
• Pagination Support: Efficient handling of large datasets
• Multiple Response Formats: JSON and Markdown outputs

Installation

Prerequisites

• Python 3.10 or higher
• Method CRM account with API access
• API key (obtain from Method CRM dashboard)

Install Dependencies

# Clone the repository
git clone https://github.com/avisangle/method-crm-mcp.git
cd method-crm-mcp

# Install dependencies
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

Configuration

1. Environment Setup

Copy the example environment file:

cp .env.example .env

2. Configure Authentication

Edit .env and set your API key:

# Required: Method CRM API Key
METHOD_API_KEY=your_api_key_here

# Optional: Customize API base URL
METHOD_API_BASE_URL=https://rest.method.me/api/v1/

# Optional: Transport configuration
METHOD_TRANSPORT=stdio        # or 'http'
METHOD_HTTP_PORT=8000         # only used if TRANSPORT=http

3. Get Your API Key

1. Log in to your Method CRM account
2. Navigate to Settings → API Settings
3. Click Create API Key (requires Administrator role)
4. Name your key (e.g., "MCP Server")
5. Copy the generated key immediately (it won't be shown again)
6. Paste it into .env as METHOD_API_KEY

Usage

Running the Server

stdio Transport (Local Use)

Default mode for use with MCP clients like Claude Desktop:

python -m method_mcp.server

Or using the module directly:

python src/method_mcp/server.py

HTTP Transport (Remote Access)

For remote access or multiple clients:

# Set transport in .env
METHOD_TRANSPORT=http
METHOD_HTTP_PORT=8000

# Start server
python -m method_mcp.server

The server will listen on http://localhost:8000

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "method-crm": {
      "command": "python",
      "args": [
        "-m",
        "method_mcp.server"
      ],
      "cwd": "/absolute/path/to/method-crm-mcp",
      "env": {
        "METHOD_API_KEY": "your_api_key_here"
      }
    }
  }
}

MCP Inspector (Testing)

Test tools using MCP Inspector:

npx @modelcontextprotocol/inspector python src/method_mcp/server.py

Available Tools

Table Operations (5 tools)

Tool	Description	Read-Only	Destructive
method_tables_query	Query records with filtering, pagination, aggregation	✅	❌
method_tables_get	Get specific record by ID with optional expansion	✅	❌
method_tables_create	Create new record in any table	❌	❌
method_tables_update	Update record fields (batch support: 50 records)	❌	❌
method_tables_delete	Delete record permanently	❌	✅

Example: Query active customers

{
  "table": "Customer",
  "filter": "Status eq 'Active'",
  "top": 50,
  "orderby": "CreatedDate desc",
  "response_format": "json"
}

Example: Create new inventory item

{
  "table": "ItemInventory",
  "fields": {
    "Name": "New Product",
    "Sku": "SKU-001",
    "SalesDesc": "Product description",
    "SalesPrice": 99.99,
    "PurchaseCost": 80,
    "PurchaseDesc": "Purchase description",
    "IsActive": true,
    "IncomeAccount": "Sales of Product Income",
    "COGSAccount": "Cost of Goods Sold",
    "AssetAccount": "Inventory",
    "PurchaseTaxCode": "Tax on Purchases",
    "SalesTaxCode": "Tax on Sales",
    "IsUsedOnPurchaseTransaction": true,
    "IsUsedOnSalesTransaction": true,
    "IsTrackQtyOnHand": true,
    "TenantID": 1
  },
  "response_format": "json"
}

Note: Required fields vary by table. For ItemInventory:

• Required: Sku (must be unique), COGSAccount, AssetAccount, TenantID
• Recommended: IncomeAccount, tax codes, transaction flags
• Account fields must match existing QuickBooks account names exactly

File Management (6 tools)

Tool	Description	Read-Only	Destructive
method_files_upload	Upload file (max 50MB) with optional record linking	❌	❌
method_files_list	List files with filtering and pagination	✅	❌
method_files_download	Download file content (base64-encoded)	✅	❌
method_files_get_url	Generate temporary download URL (20-min expiry)	✅	❌
method_files_update_link	Update file link to different table/record	❌	❌
method_files_delete	Delete file permanently	❌	✅

Example: Upload invoice PDF

{
  "filename": "invoice-2024-01.pdf",
  "content": "<base64-encoded content>",
  "link_table": "Invoice",
  "link_record_id": "INV-12345",
  "description": "January 2024 invoice"
}

User Information (1 tool)

Tool	Description	Read-Only
method_user_get_info	Get current authenticated user information	✅

Event Automation (4 tools)

Tool	Description	Read-Only	Destructive
method_events_create_routine	Create event-driven automation routine	❌	❌
method_events_list_routines	List all event routines with pagination	✅	❌
method_events_get_routine	Get specific routine details by ID	✅	❌
method_events_delete_routine	Delete event routine permanently	❌	✅

Example: Send email on new customer

{
  "name": "New Customer Welcome",
  "description": "Send welcome email to new customers",
  "trigger_config": {
    "event": "record_created",
    "table": "Customer"
  },
  "actions": [
    {
      "action": "send_email",
      "template": "welcome",
      "to_field": "Email"
    }
  ],
  "enabled": true
}

API Key Management (4 tools)

Tool	Description	Read-Only	Destructive	Admin Required
method_apikeys_create	Create new API key (returns key once)	❌	❌	✅
method_apikeys_list	List API keys (keys masked for security)	✅	❌	❌
method_apikeys_update	Update key metadata (name, permissions, status)	❌	❌	✅
method_apikeys_delete	Delete/revoke API key permanently	❌	✅	✅

Example: Create production API key

{
  "name": "Production Server",
  "description": "Main API integration key",
  "permissions": ["read:all", "write:all"]
}

API Rate Limits

Method CRM enforces the following limits:

• Per-minute: 100 requests per account
• Daily: 5,000-25,000 requests (varies by license count)
• File size: 50MB per file
• Storage: 10GB total per account
• Batch updates: 50 related records maximum

The MCP server automatically handles rate limiting with:

• Exponential backoff retry logic
• Clear error messages with retry-after timing
• Actionable suggestions for rate limit errors

Error Handling

All tools return actionable error messages with suggestions:

Example error responses:

Error: Rate limit exceeded (100 requests/minute or daily limit reached).
Retry-After: 45 seconds
Suggestion: Wait before making more requests. Method CRM limits: 100 req/min per account, 5,000-25,000 daily depending on licenses.

Error: Resource not found - Record 'CUST-999' not found in table 'Customer'
Suggestion: Verify that the table name, record ID, or file ID is correct. Use list/query tools to find the correct identifier.

Error: Permission denied - Your account doesn't have Admin role required for this operation
Suggestion: Your account doesn't have permission to perform this operation. Check that you have the required role (e.g., Admin for API key creation) or that the resource belongs to your account.

Advanced Features

OData Query Filtering

Use powerful OData-style filters for queries:

# Equality
"Status eq 'Active'"

# Comparison
"CreatedDate gt '2024-01-01'"
"Total ge 1000"

# Logical operators
"Status eq 'Active' and Total gt 500"
"Type eq 'Invoice' or Type eq 'Estimate'"

# String functions
"startswith(Name, 'John')"
"contains(Email, '@example.com')"
"endswith(Status, 'ed')"

# Null checks
"Email ne null"

Aggregations

Perform aggregations directly in queries:

# Count records
"count()"

# Sum amounts
"sum(Amount)"

# Group by with aggregation
"groupby((Status),aggregate($count as Total))"

# Multiple aggregations
"sum(Amount),average(Total),count()"

Pagination

All list/query tools support pagination:

{
  "table": "Customer",
  "top": 100,
  "skip": 0
}

Responses include pagination metadata:

{
  "total": 500,
  "count": 100,
  "offset": 0,
  "has_more": true,
  "next_offset": 100
}

Response Formats

Choose between JSON (structured) and Markdown (human-readable):

{
  "response_format": "json"    // or "markdown"
}

Architecture

method-crm-mcp/
├── src/method_mcp/
│   ├── server.py           # FastMCP server initialization
│   ├── client.py           # HTTP client with retry logic
│   ├── auth.py             # Authentication (API Key + OAuth2 placeholders)
│   ├── models.py           # Pydantic models (20 tools)
│   ├── errors.py           # Error handling utilities
│   ├── utils.py            # Shared helpers (pagination, formatting)
│   └── tools/
│       ├── tables.py       # 5 table operation tools (CRUD)
│       ├── files.py        # 6 file management tools
│       ├── user.py         # 1 user info tool
│       ├── events.py       # 4 event automation tools (complete CRUD)
│       └── apikeys.py      # 4 API key management tools (complete CRUD)
├── tests/                  # Unit and integration tests
├── evaluations/            # Evaluation questions for testing
├── pyproject.toml          # Dependencies and project metadata
├── .env.example            # Environment configuration template
└── README.md               # This file

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=src/method_mcp --cov-report=html

Code Quality

# Type checking
mypy src/method_mcp

# Linting
ruff check src/method_mcp

# Formatting
black src/method_mcp

Troubleshooting

Authentication Errors

Problem: Error: Authentication failed. Your API key or access token is invalid or expired.

Solutions:

• Verify METHOD_API_KEY is set correctly in .env
• Check that the key hasn't been revoked in Method CRM dashboard
• Ensure no extra whitespace in the key value

Rate Limiting

Problem: Error: Rate limit exceeded (100 requests/minute)

Solutions:

• Wait for the retry-after period (check error message)
• Reduce request frequency in your application
• Use pagination to reduce total requests
• Consider upgrading Method CRM license for higher limits

File Upload Errors

Problem: Error: File size exceeds 50MB limit

Solutions:

• Compress files before uploading
• Split large files into smaller chunks
• Use external storage (S3, etc.) and store URLs in Method CRM

Connection Errors

Problem: Error: Unable to connect to Method API

Solutions:

• Check internet connection
• Verify METHOD_API_BASE_URL is correct
• Check if Method CRM is experiencing downtime
• Verify firewall/proxy settings

Security Best Practices

1. API Key Storage

   • Store in environment variables, never in code
   • Use .env file (never commit to version control)
   • Rotate keys periodically (every 90 days recommended)

2. Access Control

   • Use separate API keys for different environments (dev/staging/prod)
   • Revoke unused keys promptly
   • Monitor key usage via method_apikeys_list

3. File Handling

   • Validate file types before upload
   • Scan uploaded files for malware
   • Enforce file size limits in application logic

4. Error Messages

   • Don't expose sensitive information in logs
   • Use debug mode only in development

OAuth2 Support (Coming Soon)

OAuth2 authentication is planned for a future release:

• Authorization Code Flow: User-based authentication
• Client Credentials Flow: Machine-to-machine with token refresh
• Implicit Flow: Browser-based SPAs

Placeholders are already in the codebase (auth.py).

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request

Support

• Issues: Report bugs and request features on GitHub
• Documentation: https://developer.method.me/
• Method CRM Support: https://help.method.me/

License

MIT License - See LICENSE file for details.

Changelog

Version 1.0.0 (2025-11-22)

Initial Public Release

• ✅ 20 fully implemented tools (complete API coverage)
• ✅ API Key authentication
• ✅ Dual transport support (stdio + HTTP)
• ✅ Rate limiting and retry logic
• ✅ Comprehensive error handling
• ✅ Pydantic validation for all inputs
• ✅ Pagination support with cursor-based navigation
• ✅ Multiple response formats (JSON/Markdown)
• ✅ File operations with multipart/form-data support
• ✅ Complete CRUD for tables, events, and API keys
• ⏳ OAuth2 support (placeholders added)

---

Built with ❤️ using FastMCP and the Model Context Protocol