Method Crm

方法CRM MCP服务器

用于方法CRM API集成的生产就绪模型上下文协议（MCP）服务器。该服务器使LLM能够通过精心设计的表、文件、用户、事件和API密钥管理工具与方法CRM数据交互。

特性

• 20个综合工具 涵盖所有方法CRM操作
• API密钥验证 （完全实现）使用OAuth2占位符
• 双重运输支持：stdio（本地）和可流式传输HTTP（远程）
• 速率限制和重试逻辑：API限值的自动处理
• 类型安全：对所有输入进行完整的Pydantic验证
• 可操作错误：清除带有建议的错误消息
• 分页支持：高效处理大型数据集
• 多种响应格式：JSON和Markdown输出

安装

先决条件

• Python 3.10或更高版本
• 使用API访问的方法CRM帐户
• API密钥（从方法CRM仪表板获取）

再进行

# 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]"

配置

1.环境设置

复制示例环境文件：

cp .env.example .env

2.配置身份验证

编辑 .env 并设置您的API密钥：

# 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.获取API密钥

1. 登录您的Method CRM帐户
2. 引导到 设置 → API设置
3. 点击 创建API密钥 （需要管理员角色）
4. 命名您的密钥（例如，“MCP服务器”）
5. 立即复制生成的密钥（不会再次显示）
6. 将其粘贴到 .env 作为 METHOD_API_KEY

用法

运行服务器

stdio传输（本地使用）

与Claude Desktop等MCP客户端一起使用的默认模式：

python -m method_mcp.server

或者直接使用该模块：

python src/method_mcp/server.py

HTTP传输（远程访问）

对于远程访问或多个客户端：

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

# Start server
python -m method_mcp.server

服务器将监听 http://localhost:8000

MCP客户端配置

克劳德桌面

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在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检验员（测试）

使用MCP Inspector的测试工具：

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

可用工具

表操作（5个工具）

示例：查询活跃客户

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

示例：创建新的库存项目

{
  "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"
}

备注：必填字段因表而异。对于 ItemInventory:

• 必需: Sku （必须是唯一的）， COGSAccount, AssetAccount, TenantID
• 推荐: IncomeAccount、税码、交易标志
• 帐户字段必须与现有QuickBooks帐户名完全匹配

文件管理（6个工具）

示例：上传发票PDF

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

用户信息（1个工具）

事件自动化（4个工具）

示例：发送关于新客户的电子邮件

{
  "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密钥管理（4个工具）

示例：创建生产API密钥

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

API费率限制

方法CRM强制执行以下限制：

• 每分钟：每个帐户100个请求
• 每日：5000-25000个请求（因许可证数量而异）
• 文件大小：每个文件50MB
• 存储：每个帐户总计10GB
• 批量更新：最多50条相关记录

MCP服务器通过以下方式自动处理速率限制：

• 指数退避重试逻辑
• 定时后重试，清除错误消息
• 针对利率限制错误的可操作建议

错误处理

所有工具都会返回可操作的错误消息和建议：

错误响应示例:

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.

高级功能

OData查询筛选

对查询使用强大的OData样式过滤器：

# 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"

聚合

直接在查询中执行聚合：

# Count records
"count()"

# Sum amounts
"sum(Amount)"

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

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

分页

所有列表/查询工具都支持分页：

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

响应包括分页元数据：

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

响应格式

在JSON（结构化）和Markdown（人类可读）之间进行选择：

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

建筑

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

发展

运行测试

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

# Run all tests
pytest

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

代码质量

# Type checking
mypy src/method_mcp

# Linting
ruff check src/method_mcp

# Formatting
black src/method_mcp

故障排除

身份验证错误

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

解决方案:

• 验证 METHOD_API_KEY 在中设置正确 .env
• 检查Method CRM仪表板中的密钥是否未被撤销
• 确保键值中没有多余的空格

速率限制

问题: Error: Rate limit exceeded (100 requests/minute)

解决方案:

• 等待一段时间后重试（检查错误消息）
• 降低应用程序中的请求频率
• 使用分页来减少总请求数
• 考虑升级Method CRM许可证以获得更高的限制

文件上传错误

问题: Error: File size exceeds 50MB limit

解决方案:

• 上传前压缩文件
• 将大文件分割成更小的块
• 使用外部存储（S3等）并将URL存储在Method CRM中

连接错误

问题: Error: Unable to connect to Method API

解决方案:

• 检查互联网连接
• 验证 METHOD_API_BASE_URL 是正确的
• 检查Method CRM是否出现停机
• 验证防火墙/代理设置

安全最佳实践

1. API密钥存储

- 存储在环境变量中，从不存储在代码中 - 使用 .env 文件（从不提交版本控制） - 定期旋转按键（建议每90天一次）

1. 访问控制

- 针对不同的环境使用单独的API密钥（dev/staining/prod） - 及时撤销未使用的密钥 - 通过以下方式监控密钥使用情况 method_apikeys_list

1. 文件处理

- 上传前验证文件类型 - 扫描上传的文件以查找恶意软件 - 在应用程序逻辑中强制执行文件大小限制

1. 错误消息

- 不要在日志中暴露敏感信息 - 仅在开发中使用调试模式

OAuth2支持（即将推出）

OAuth2身份验证计划在未来的版本中发布：

• 授权码流：基于用户的身份验证
• 客户端凭据流：使用令牌刷新的机器对机器
• 隐式流：基于浏览器的SPA

占位符已经在代码库中(auth.py).

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求

支持

• 问题：在GitHub上报告错误和请求功能
• 文档: https://developer.method.me/
• 方法CRM支持: https://help.method.me/

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

更新日志

版本1.0.0（2025-11-22）

首次公开发布

• ✅ 20个完全实现的工具（API覆盖范围完整）
• ✅ API密钥验证
• ✅ 双传输支持（stdio+HTTP）
• ✅ 速率限制和重试逻辑
• ✅ 全面的错误处理
• ✅ 所有输入的Pydantic验证
• ✅ 基于光标导航的分页支持
• ✅ 多种响应格式（JSON/Markdown）
• ✅ 支持多部分/表单数据的文件操作
• ✅ 完成表、事件和API键的CRUD
• ⏳ OAuth2支持（添加占位符）

______________________________________________________________________