Connectwise MCP Server (connectwise-mcp-server)

ConnectWise MCP服务器

概述

ConnectWise MCP服务器是一个基于Docker的模型上下文协议（MCP）桥，使AI代理能够通过自然语言命令访问ConnectWise Manage数据。它提供对ConnectWise实例的只读访问，允许通过OpenWebUI进行人工智能辅助的数据检索和分析。

服务器由两个组件组成：

1. MCP服务器 -基于Python的ConnectWise管理API接口
2. MCP电桥 -Node.js Express服务器公开用于OpenWebUI的HTTP API

┌─────────────────┐     ┌──────────────────┐      ┌─────────────────┐      ┌────────────────┐
│   OpenWebUI     │◄───►│   MCP Bridge     │◄───► │ ConnectWise     │◄────►│ ConnectWise    │
│     Tools       │ HTTP│   (Port 3002)    │Docker│  MCP Server     │HTTPS │   Manage API   │
└─────────────────┘     └──────────────────┘      └─────────────────┘      └────────────────┘

主要特点

公司管理层：

• 使用高级过滤功能搜索公司
• 检索完整的公司信息
• 查看公司联系人和关系

服务票：

• 使用ConnectWise条件搜索门票
• 检索完整的门票详细信息，包括备注和历史记录
• 按状态、公司、日期等筛选

联系与销售：

• 搜索和检索与公司协会的联系人
• 查看销售机会和渠道跟踪
• 访问机会详细信息和状态

协议和时间跟踪：

• 搜索协议和合同
• 查看协议添加和附加组件
• 查看详细的时间跟踪数据
• 按成员、日期或票证筛选时间条目

项目与活动管理：

• 搜索项目并跟踪进度
• 查看活动和任务
• 访问团队成员信息

IT资产管理：

• 搜索和查看IT配置/资产
• 检索资产分类的配置类型
• 访问公司网站和位置
• 跟踪硬件和软件库存

财务与账单：

• 搜索和检索发票
• 查看费用条目和报告
• 访问定期计费的计费周期
• 查看协议添加和账单详细信息

参考数据：

• 用于分类的公司类型和状态
• 门票优先级和来源
• 组织的联系人类型
• 服务板配置和状态

服务台增强功能：

• 查看服务板和工作流程
• 访问板特定状态
• 检索票务任务和清单
• 查看门票的预定工作

AI集成：

• OpenWebUI中的自然语言命令支持
• 对所有ConnectWise数据的只读访问
• 高级过滤和搜索功能

先决条件

• 已安装Docker和Docker Compose
• ConnectWise管理API凭据（公司ID、公钥、私钥）
• OpenWebUI正在运行（任何支持工具的版本）

快速开始

1.克隆存储库

git clone https://github.com/taddiemason/Connectwise-MCP-Server
cd ConnectWise-MCP-Server

2.获取ConnectWise凭据

要获取ConnectWise API凭据，请执行以下操作：

1. 登录您的ConnectWise Manage实例
2. 引导到 系统→ 成员
3. 新建API成员或使用现有凭据
4. 生成API密钥：

- 首选 我的账户→ API密钥 - 点击 新 创建新的API密钥 - 保存 公钥 和 私钥

1. 你的 公司ID 通常显示在URL或系统设置中

重要提示： 对于只读访问，请确保API成员在ConnectWise中仅具有读取权限。

3.配置凭据

创建一个 .env 示例中的文件：

cp .env.example .env

编辑 .env 并添加您的ConnectWise凭据：

# ConnectWise API Credentials (required)
CW_COMPANY_ID=your_company_id_here
CW_PUBLIC_KEY=your_public_key_here
CW_PRIVATE_KEY=your_private_key_here

# ConnectWise API Configuration
CW_API_URL=https://api-na.myconnectwise.net
CW_API_VERSION=v2023.2
CW_CLIENT_ID=mcp-connectwise-server

# MCP Bridge Server Port (default: 3002)
MCP_PORT=3002

# Log level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

API URL配置：

• 北美： https://api-na.myconnectwise.net
• 欧洲： https://api-eu.myconnectwise.net
• 澳大利亚： https://api-au.myconnectwise.net
• 内部部署：使用您的服务器URL

4.启动服务

使用安装脚本（推荐）：

chmod +x setup.sh
./setup.sh

选择选项1启动服务器。

或者手动使用Docker Compose：

docker-compose up -d --build

桥位于： http://localhost:3002

5.向OpenWebUI添加工具

1. 在浏览器中打开OpenWebUI
2. 引导到 设置→ 管理面板→ Tools
3. 点击 “+创建新工具”
4. 复制以下内容 connectwise_tools.py 来自此存储库
5. 粘贴到工具编辑器中
6. 在“阀门”部分配置网桥URL：

- Docker： http://connectwise-mcp-bridge:3002 - 当地： http://localhost:3002

1. 点击 “保存”
2. 启用ConnectWise工具

6.验证安装

curl http://localhost:3002/health

预期响应：

{
  "status": "ok",
  "service": "connectwise-mcp-bridge"
}

OpenWebUI中的可用工具

公司工具：

• get_companies() -使用高级过滤功能搜索公司
• get_company() -获取具体的公司详细信息
• get_company_sites() -获取特定公司的站点/位置
• get_company_types() -获取所有公司类型进行分类
• get_company_statuses() -获取所有公司状态

票证工具：

• get_tickets() -搜索有条件的门票
• get_ticket() -获取特定门票详细信息
• get_ticket_notes() -检索门票备注和历史记录
• get_ticket_tasks() -获取工单任务/清单项目
• get_ticket_schedules() -获得预定的工作票
• get_ticket_priorities() -获取所有票优先级
• get_ticket_sources() -获取所有票源

联系工具：

• get_contacts() -搜索联系人
• get_contact() -获取具体联系方式
• get_contact_types() -获取所有联系人类型

销售工具：

• get_opportunities() -搜索销售机会

协议工具：

• get_agreements() -搜索协议和合同
• get_agreement_additions() -获取特定协议的附加组件

时间输入工具：

• get_time_entries() -搜索时间跟踪数据

项目工具：

• get_projects() -搜索项目

活动工具：

• get_activities() -搜索活动和任务

成员工具：

• get_members() -搜索团队成员

IT资产管理工具：

• get_configurations() -搜索IT配置/资产
• get_configuration() -按ID获取具体配置
• get_configuration_types() -获取所有配置类型

财务和计费工具：

• get_invoices() -搜索和检索发票
• get_expense_entries() -搜索费用条目
• get_billing_cycles() -获取所有计费周期

服务台工具：

• get_service_boards() -获取所有服务板
• get_board_statuses() -获取特定电路板的状态

所有工具都支持分页和ConnectWise条件语法，用于高级过滤。

使用示例

在OpenWebUI中，自然沟通：

一般查询：

• “给我看ACME公司的所有未结门票”
• “查找所有名称中包含‘Tech’的公司”
• “获取12345号票的详细信息”
• “列出状态为“打开”的所有机会”
• “显示本周的时间条目”
• “在Microsoft查找联系人”
• “目前正在进行哪些项目？”
• “显示本月到期的所有协议”

IT资产管理：

• “显示ACME Corp的所有服务器”
• “为票证#5678分配了哪些配置？”
• “列出XYZ公司的所有公司网站”
• “我们有哪些配置类型？”

财务与账单：

• “显示本月所有未结发票”
• “约翰本周的开支是多少？”
• “列出所有计费周期”
• “123号协议中包含哪些附加组件？”

服务台：

• “我们有什么服务委员会？”
• “显示帮助台板的所有状态”
• “9999号票上有什么任务？”
• “显示1234号票的预定工作”

参考数据：

• “有哪些公司类型可供选择？”
• “列出所有票优先级”
• “显示所有联系人类型”
• “我们追踪哪些门票来源？”

AI将自动调用相应的ConnectWise工具函数来完成您的请求。

ConnectWise API条件

ConnectWise使用强大的条件语法进行过滤：

# String equality
identifier="ACME"

# Contains (like)
name like "%Corp%"

# Date comparisons
dateEntered > [2024-01-01]

# Numeric comparisons
id > 1000

# Multiple conditions
status/name="New" and company/identifier="ACME"

# Nested fields
company/name like "%Tech%"

文件结构

ConnectWise-MCP-Server/
├── connectwise_mcp.py      (MCP server implementation)
├── bridge-server.js        (HTTP API bridge)
├── connectwise_tools.py    (OpenWebUI tool)
├── docker-compose.yml      (Multi-container setup)
├── Dockerfile              (MCP server container)
├── Dockerfile.bridge       (Bridge server container)
├── requirements.txt        (Python dependencies)
├── .env.example            (Environment template)
├── setup.sh                (Management script)
└── README.md               (This file)

管理命令

使用安装脚本：

./setup.sh

选项：

1. 启动ConnectWise MCP服务器
2. 停止ConnectWise MCP服务器
3. 重新启动ConnectWise MCP服务器
4. 查看日志
5. 检查状态
6. 更新服务器
7. 清理
8. 退出

直接Docker命令：

# Start servers
docker-compose up -d --build

# View logs
docker-compose logs -f

# View bridge logs only
docker-compose logs -f mcp-bridge

# View MCP server logs only
docker-compose logs -f connectwise-mcp-server

# Stop servers
docker-compose down

# Restart servers
docker-compose restart

# Check status
docker-compose ps

故障排除

身份验证错误：

• 验证您的公司ID、公钥和私钥是否正确
• 确保API成员具有适当的权限
• 检查API URL是否与ConnectWise实例匹配
• 如果需要，生成新的API密钥

端口冲突：

如果端口3002已在使用中：

1. 编辑 .env 文件： MCP_PORT=3003
2. 编辑 docker-compose.yml：将端口映射更新为 3003:3002 和环境 PORT=3003
3. 重新启动： docker-compose down && docker-compose up -d --build
4. 更新OpenWebUI工具阀中的网桥URL

桥梁连接问题：

• 验证网桥是否正在运行： docker-compose ps
• 检查桥梁日志： docker-compose logs mcp-bridge
• 测试健康终点： curl http://localhost:3002/health
• 验证OpenWebUI工具阀设置中的网桥URL：

- 两者都在Docker中： http://connectwise-mcp-bridge:3002 - 本地 OpenWebUI: http://localhost:3002

OpenWebUI无法连接：

• 确保 connectwise_tools.py 保存在OpenWebUI工具中
• 在OpenWebUI设置中启用ConnectWise工具
• 验证阀门设置中的桥接URL是否正确
• 检查Docker网络： docker network connect openwebui_network connectwise-mcp-bridge

速率限制：

ConnectWise有API速率限制。如果遇到速率限制：

• 减少 pageSize 参数
• 增加请求之间的延迟
• 查看ConnectWise API文档了解当前限制

安全最佳实践

• 永不承诺 .env 具有版本控制真实凭据的文件
• 仅使用具有最低权限的API成员帐户
• 只读访问： 此服务器仅设计用于只读操作
• 定期轮换API证书
• 如果可能，限制对ConnectWise API的IP访问
• 尽可能在专用网络中运行网桥服务器
• 监控API使用情况并设置配额

开发与测试

地方发展：

MCP服务器：

cd ConnectWise-MCP-Server
pip install -r requirements.txt
export CW_COMPANY_ID=your_company_id
export CW_PUBLIC_KEY=your_public_key
export CW_PRIVATE_KEY=your_private_key
python connectwise_mcp.py

网桥服务器：

npm install express cors
export MCP_PORT=3002
node bridge-server.js

测试API端点：

健康检查：

curl http://localhost:3002/health

测试搜索：

curl -X POST http://localhost:3002/v1/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "connectwise_get_companies",
    "arguments": {
      "conditions": "identifier=\"ACME\"",
      "pageSize": 5
    }
  }'

依赖项

Python包（connectwise mcp服务器）：

• mcp-模型上下文协议框架
• fastmcp-快速MCP服务器实现
• httpx-异步HTTP客户端
• pydantic-数据验证

Node.js包（mcp-bridge）：

• express-Web服务器框架
• cors-cors中间件

资源

• ConnectWise开发者网络
• 模型上下文协议（MCP）
• OpenWeb用户界面
• ConnectWise REST API文档

重要说明

• 此服务器提供 只读的 访问ConnectWise
• 未执行任何写入操作
• 专为人工智能辅助数据检索和分析而设计
• 尊重ConnectWise API费率限制
• 需要有效的ConnectWise API凭据

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

支持

对于问题、疑问或贡献：

• 在GitHub上打开一个问题
• 检查现有文档
• 查看ConnectWise API文档
• 查看OpenWebUI文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件

版本

当前版本： 1.1.0

更新日志

版本1.1.0（增强功能集）

• 增加了IT资产管理（配置、配置类型、公司站点）
• 新增财务和计费（发票、费用条目、计费周期、协议添加）
• 添加了参考数据端点（公司类型/状态、工单优先级/来源、联系人类型）
• 增加了服务台增强功能（服务板、板状态、工单任务、工单时间表）
• 总共18个新的只读工具
• 通过新的使用示例增强文档

1.0.0版本（首次发布）

• ConnectWise Manage的只读访问权限
• 对公司、门票、联系人、机会、协议的支持
• 时间条目、项目、活动和成员
• 基于Docker的部署
• OpenWebUI集成
• MCP网桥架构
• 全面的文件