Method CRM MCP Server

1# Method CRM MCP Server
2 
3A 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.
4 
5## Features
6 
7- **20 Comprehensive Tools** covering all Method CRM operations
8- **API Key Authentication** (fully implemented) with OAuth2 placeholders
9- **Dual Transport Support**: stdio (local) and streamable HTTP (remote)
10- **Rate Limiting & Retry Logic**: Automatic handling of API limits
11- **Type-Safe**: Full Pydantic validation for all inputs
12- **Actionable Errors**: Clear error messages with suggestions
13- **Pagination Support**: Efficient handling of large datasets
14- **Multiple Response Formats**: JSON and Markdown outputs
15 
16## Installation
17 
18### Prerequisites
19 
20- Python 3.10 or higher
21- Method CRM account with API access
22- API key (obtain from Method CRM dashboard)
23 
24### Install Dependencies
25 
26```bash
27# Clone the repository
28git clone https://github.com/avisangle/method-crm-mcp.git
29cd method-crm-mcp
30 
31# Install dependencies
32pip install -e .
33 
34# Or install with dev dependencies
35pip install -e ".[dev]"
36```
37 
38## Configuration
39 
40### 1. Environment Setup
41 
42Copy the example environment file:
43 
44```bash
45cp .env.example .env
46```
47 
48### 2. Configure Authentication
49 
50Edit `.env` and set your API key:
51 
52```bash
53# Required: Method CRM API Key
54METHOD_API_KEY=your_api_key_here
55 
56# Optional: Customize API base URL
57METHOD_API_BASE_URL=https://rest.method.me/api/v1/
58 
59# Optional: Transport configuration
60METHOD_TRANSPORT=stdio        # or 'http'
61METHOD_HTTP_PORT=8000         # only used if TRANSPORT=http
62```
63 
64### 3. Get Your API Key
65 
661. Log in to your Method CRM account
672. Navigate to **Settings** → **API Settings**
683. Click **Create API Key** (requires Administrator role)
694. Name your key (e.g., "MCP Server")
705. Copy the generated key immediately (it won't be shown again)
716. Paste it into `.env` as `METHOD_API_KEY`
72 
73## Usage
74 
75### Running the Server
76 
77#### stdio Transport (Local Use)
78 
79Default mode for use with MCP clients like Claude Desktop:
80 
81```bash
82python -m method_mcp.server
83```
84 
85Or using the module directly:
86 
87```bash
88python src/method_mcp/server.py
89```
90 
91#### HTTP Transport (Remote Access)
92 
93For remote access or multiple clients:
94 
95```bash
96# Set transport in .env
97METHOD_TRANSPORT=http
98METHOD_HTTP_PORT=8000
99 
100# Start server
101python -m method_mcp.server
102```
103 
104The server will listen on `http://localhost:8000`
105 
106### MCP Client Configuration
107 
108#### Claude Desktop
109 
110Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
111 
112```json
113{
114  "mcpServers": {
115    "method-crm": {
116      "command": "python",
117      "args": [
118        "-m",
119        "method_mcp.server"
120      ],
121      "cwd": "/absolute/path/to/method-crm-mcp",
122      "env": {
123        "METHOD_API_KEY": "your_api_key_here"
124      }
125    }
126  }
127}
128```
129 
130#### MCP Inspector (Testing)
131 
132Test tools using MCP Inspector:
133 
134```bash
135npx @modelcontextprotocol/inspector python src/method_mcp/server.py
136```
137 
138## Available Tools
139 
140### Table Operations (5 tools)
141 
142| Tool | Description | Read-Only | Destructive |
143|------|-------------|-----------|-------------|
144| `method_tables_query` | Query records with filtering, pagination, aggregation | ✅ | ❌ |
145| `method_tables_get` | Get specific record by ID with optional expansion | ✅ | ❌ |
146| `method_tables_create` | Create new record in any table | ❌ | ❌ |
147| `method_tables_update` | Update record fields (batch support: 50 records) | ❌ | ❌ |
148| `method_tables_delete` | Delete record permanently | ❌ | ✅ |
149 
150**Example**: Query active customers
151```json
152{
153  "table": "Customer",
154  "filter": "Status eq 'Active'",
155  "top": 50,
156  "orderby": "CreatedDate desc",
157  "response_format": "json"
158}
159```
160 
161**Example**: Create new inventory item
162```json
163{
164  "table": "ItemInventory",
165  "fields": {
166    "Name": "New Product",
167    "Sku": "SKU-001",
168    "SalesDesc": "Product description",
169    "SalesPrice": 99.99,
170    "PurchaseCost": 80,
171    "PurchaseDesc": "Purchase description",
172    "IsActive": true,
173    "IncomeAccount": "Sales of Product Income",
174    "COGSAccount": "Cost of Goods Sold",
175    "AssetAccount": "Inventory",
176    "PurchaseTaxCode": "Tax on Purchases",
177    "SalesTaxCode": "Tax on Sales",
178    "IsUsedOnPurchaseTransaction": true,
179    "IsUsedOnSalesTransaction": true,
180    "IsTrackQtyOnHand": true,
181    "TenantID": 1
182  },
183  "response_format": "json"
184}
185```
186**Note**: Required fields vary by table. For `ItemInventory`:
187- **Required**: `Sku` (must be unique), `COGSAccount`, `AssetAccount`, `TenantID`
188- **Recommended**: `IncomeAccount`, tax codes, transaction flags
189- Account fields must match existing QuickBooks account names exactly
190 
191### File Management (6 tools)
192 
193| Tool | Description | Read-Only | Destructive |
194|------|-------------|-----------|-------------|
195| `method_files_upload` | Upload file (max 50MB) with optional record linking | ❌ | ❌ |
196| `method_files_list` | List files with filtering and pagination | ✅ | ❌ |
197| `method_files_download` | Download file content (base64-encoded) | ✅ | ❌ |
198| `method_files_get_url` | Generate temporary download URL (20-min expiry) | ✅ | ❌ |
199| `method_files_update_link` | Update file link to different table/record | ❌ | ❌ |
200| `method_files_delete` | Delete file permanently | ❌ | ✅ |
201 
202**Example**: Upload invoice PDF
203```json
204{
205  "filename": "invoice-2024-01.pdf",
206  "content": "<base64-encoded content>",
207  "link_table": "Invoice",
208  "link_record_id": "INV-12345",
209  "description": "January 2024 invoice"
210}
211```
212 
213### User Information (1 tool)
214 
215| Tool | Description | Read-Only |
216|------|-------------|-----------|
217| `method_user_get_info` | Get current authenticated user information | ✅ |
218 
219### Event Automation (4 tools)
220 
221| Tool | Description | Read-Only | Destructive |
222|------|-------------|-----------|-------------|
223| `method_events_create_routine` | Create event-driven automation routine | ❌ | ❌ |
224| `method_events_list_routines` | List all event routines with pagination | ✅ | ❌ |
225| `method_events_get_routine` | Get specific routine details by ID | ✅ | ❌ |
226| `method_events_delete_routine` | Delete event routine permanently | ❌ | ✅ |
227 
228**Example**: Send email on new customer
229```json
230{
231  "name": "New Customer Welcome",
232  "description": "Send welcome email to new customers",
233  "trigger_config": {
234    "event": "record_created",
235    "table": "Customer"
236  },
237  "actions": [
238    {
239      "action": "send_email",
240      "template": "welcome",
241      "to_field": "Email"
242    }
243  ],
244  "enabled": true
245}
246```
247 
248### API Key Management (4 tools)
249 
250| Tool | Description | Read-Only | Destructive | Admin Required |
251|------|-------------|-----------|-------------|----------------|
252| `method_apikeys_create` | Create new API key (returns key once) | ❌ | ❌ | ✅ |
253| `method_apikeys_list` | List API keys (keys masked for security) | ✅ | ❌ | ❌ |
254| `method_apikeys_update` | Update key metadata (name, permissions, status) | ❌ | ❌ | ✅ |
255| `method_apikeys_delete` | Delete/revoke API key permanently | ❌ | ✅ | ✅ |
256 
257**Example**: Create production API key
258```json
259{
260  "name": "Production Server",
261  "description": "Main API integration key",
262  "permissions": ["read:all", "write:all"]
263}
264```
265 
266## API Rate Limits
267 
268Method CRM enforces the following limits:
269 
270- **Per-minute**: 100 requests per account
271- **Daily**: 5,000-25,000 requests (varies by license count)
272- **File size**: 50MB per file
273- **Storage**: 10GB total per account
274- **Batch updates**: 50 related records maximum
275 
276The MCP server automatically handles rate limiting with:
277- Exponential backoff retry logic
278- Clear error messages with retry-after timing
279- Actionable suggestions for rate limit errors
280 
281## Error Handling
282 
283All tools return actionable error messages with suggestions:
284 
285**Example error responses**:
286 
287```
288Error: Rate limit exceeded (100 requests/minute or daily limit reached).
289Retry-After: 45 seconds
290Suggestion: Wait before making more requests. Method CRM limits: 100 req/min per account, 5,000-25,000 daily depending on licenses.
291```
292 
293```
294Error: Resource not found - Record 'CUST-999' not found in table 'Customer'
295Suggestion: Verify that the table name, record ID, or file ID is correct. Use list/query tools to find the correct identifier.
296```
297 
298```
299Error: Permission denied - Your account doesn't have Admin role required for this operation
300Suggestion: 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.
301```
302 
303## Advanced Features
304 
305### OData Query Filtering
306 
307Use powerful OData-style filters for queries:
308 
309```
310# Equality
311"Status eq 'Active'"
312 
313# Comparison
314"CreatedDate gt '2024-01-01'"
315"Total ge 1000"
316 
317# Logical operators
318"Status eq 'Active' and Total gt 500"
319"Type eq 'Invoice' or Type eq 'Estimate'"
320 
321# String functions
322"startswith(Name, 'John')"
323"contains(Email, '@example.com')"
324"endswith(Status, 'ed')"
325 
326# Null checks
327"Email ne null"
328```
329 
330### Aggregations
331 
332Perform aggregations directly in queries:
333 
334```
335# Count records
336"count()"
337 
338# Sum amounts
339"sum(Amount)"
340 
341# Group by with aggregation
342"groupby((Status),aggregate($count as Total))"
343 
344# Multiple aggregations
345"sum(Amount),average(Total),count()"
346```
347 
348### Pagination
349 
350All list/query tools support pagination:
351 
352```json
353{
354  "table": "Customer",
355  "top": 100,
356  "skip": 0
357}
358```
359 
360Responses include pagination metadata:
361 
362```json
363{
364  "total": 500,
365  "count": 100,
366  "offset": 0,
367  "has_more": true,
368  "next_offset": 100
369}
370```
371 
372### Response Formats
373 
374Choose between JSON (structured) and Markdown (human-readable):
375 
376```json
377{
378  "response_format": "json"    // or "markdown"
379}
380```
381 
382## Architecture
383 
384```
385method-crm-mcp/
386├── src/method_mcp/
387│   ├── server.py           # FastMCP server initialization
388│   ├── client.py           # HTTP client with retry logic
389│   ├── auth.py             # Authentication (API Key + OAuth2 placeholders)
390│   ├── models.py           # Pydantic models (20 tools)
391│   ├── errors.py           # Error handling utilities
392│   ├── utils.py            # Shared helpers (pagination, formatting)
393│   └── tools/
394│       ├── tables.py       # 5 table operation tools (CRUD)
395│       ├── files.py        # 6 file management tools
396│       ├── user.py         # 1 user info tool
397│       ├── events.py       # 4 event automation tools (complete CRUD)
398│       └── apikeys.py      # 4 API key management tools (complete CRUD)
399├── tests/                  # Unit and integration tests
400├── evaluations/            # Evaluation questions for testing
401├── pyproject.toml          # Dependencies and project metadata
402├── .env.example            # Environment configuration template
403└── README.md               # This file
404```
405 
406## Development
407 
408### Running Tests
409 
410```bash
411# Install dev dependencies
412pip install -e ".[dev]"
413 
414# Run all tests
415pytest
416 
417# Run with coverage
418pytest --cov=src/method_mcp --cov-report=html
419```
420 
421### Code Quality
422 
423```bash
424# Type checking
425mypy src/method_mcp
426 
427# Linting
428ruff check src/method_mcp
429 
430# Formatting
431black src/method_mcp
432```
433 
434## Troubleshooting
435 
436### Authentication Errors
437 
438**Problem**: `Error: Authentication failed. Your API key or access token is invalid or expired.`
439 
440**Solutions**:
441- Verify `METHOD_API_KEY` is set correctly in `.env`
442- Check that the key hasn't been revoked in Method CRM dashboard
443- Ensure no extra whitespace in the key value
444 
445### Rate Limiting
446 
447**Problem**: `Error: Rate limit exceeded (100 requests/minute)`
448 
449**Solutions**:
450- Wait for the retry-after period (check error message)
451- Reduce request frequency in your application
452- Use pagination to reduce total requests
453- Consider upgrading Method CRM license for higher limits
454 
455### File Upload Errors
456 
457**Problem**: `Error: File size exceeds 50MB limit`
458 
459**Solutions**:
460- Compress files before uploading
461- Split large files into smaller chunks
462- Use external storage (S3, etc.) and store URLs in Method CRM
463 
464### Connection Errors
465 
466**Problem**: `Error: Unable to connect to Method API`
467 
468**Solutions**:
469- Check internet connection
470- Verify `METHOD_API_BASE_URL` is correct
471- Check if Method CRM is experiencing downtime
472- Verify firewall/proxy settings
473 
474## Security Best Practices
475 
4761. **API Key Storage**
477   - Store in environment variables, never in code
478   - Use `.env` file (never commit to version control)
479   - Rotate keys periodically (every 90 days recommended)
480 
4812. **Access Control**
482   - Use separate API keys for different environments (dev/staging/prod)
483   - Revoke unused keys promptly
484   - Monitor key usage via `method_apikeys_list`
485 
4863. **File Handling**
487   - Validate file types before upload
488   - Scan uploaded files for malware
489   - Enforce file size limits in application logic
490 
4914. **Error Messages**
492   - Don't expose sensitive information in logs
493   - Use debug mode only in development
494 
495## OAuth2 Support (Coming Soon)
496 
497OAuth2 authentication is planned for a future release:
498 
499- **Authorization Code Flow**: User-based authentication
500- **Client Credentials Flow**: Machine-to-machine with token refresh
501- **Implicit Flow**: Browser-based SPAs
502 
503Placeholders are already in the codebase (`auth.py`).
504 
505## Contributing
506 
507Contributions are welcome! Please:
508 
5091. Fork the repository
5102. Create a feature branch
5113. Add tests for new features
5124. Ensure all tests pass
5135. Submit a pull request
514 
515## Support
516 
517- **Issues**: Report bugs and request features on GitHub
518- **Documentation**: https://developer.method.me/
519- **Method CRM Support**: https://help.method.me/
520 
521## License
522 
523MIT License - See [LICENSE](LICENSE) file for details.
524 
525## Changelog
526 
527### Version 1.0.0 (2025-11-22)
528 
529**Initial Public Release**
530- ✅ 20 fully implemented tools (complete API coverage)
531- ✅ API Key authentication
532- ✅ Dual transport support (stdio + HTTP)
533- ✅ Rate limiting and retry logic
534- ✅ Comprehensive error handling
535- ✅ Pydantic validation for all inputs
536- ✅ Pagination support with cursor-based navigation
537- ✅ Multiple response formats (JSON/Markdown)
538- ✅ File operations with multipart/form-data support
539- ✅ Complete CRUD for tables, events, and API keys
540- ⏳ OAuth2 support (placeholders added)
541 
542---
543 
544**Built with** ❤️ **using** [FastMCP](https://github.com/modelcontextprotocol/python-sdk) **and the** [Model Context Protocol](https://modelcontextprotocol.io)
545