ConnectWise MCP Server

Overview

The ConnectWise MCP Server is a Docker-based Model Context Protocol (MCP) bridge that enables AI agents to access ConnectWise Manage data through natural language commands. It provides read-only access to your ConnectWise instance, allowing AI-assisted data retrieval and analysis through OpenWebUI.

The server consists of two components:

1. MCP Server - Python-based ConnectWise Manage API interface
2. MCP Bridge - Node.js Express server exposing an HTTP API for OpenWebUI

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

Key Features

Company Management:

• Search companies with advanced filtering
• Retrieve complete company information
• View company contacts and relationships

Service Tickets:

• Search tickets using ConnectWise conditions
• Retrieve full ticket details including notes and history
• Filter by status, company, date, and more

Contact & Sales:

• Search and retrieve contacts with company associations
• View sales opportunities and pipeline tracking
• Access opportunity details and status

Agreements & Time Tracking:

• Search agreements and contracts
• View agreement additions and add-ons
• View detailed time tracking data
• Filter time entries by member, date, or ticket

Project & Activity Management:

• Search projects and track progress
• View activities and tasks
• Access team member information

IT Asset Management:

• Search and view IT configurations/assets
• Retrieve configuration types for asset categorization
• Access company sites and locations
• Track hardware and software inventory

Finance & Billing:

• Search and retrieve invoices
• View expense entries and reports
• Access billing cycles for recurring billing
• Review agreement additions and billing details

Reference Data:

• Company types and statuses for categorization
• Ticket priorities and sources
• Contact types for organization
• Service board configurations and statuses

Service Desk Enhancements:

• View service boards and workflows
• Access board-specific statuses
• Retrieve ticket tasks and checklists
• View scheduled work for tickets

AI Integration:

• Natural language command support in OpenWebUI
• Read-only access to all ConnectWise data
• Advanced filtering and search capabilities

Prerequisites

• Docker and Docker Compose installed
• ConnectWise Manage API credentials (Company ID, Public Key, Private Key)
• OpenWebUI running (any version with Tools support)

Quick Start

1. Clone Repository

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

2. Obtain ConnectWise Credentials

To get your ConnectWise API credentials:

1. Log in to your ConnectWise Manage instance
2. Navigate to System → Members
3. Create a new API Member or use existing credentials
4. Generate API Keys:
   • Go to My Account → API Keys
   • Click New to create new API keys
   • Save the Public Key and Private Key
5. Your Company ID is typically shown in the URL or system settings

Important: For read-only access, ensure the API member only has read permissions in ConnectWise.

3. Configure Credentials

Create a .env file from the example:

cp .env.example .env

Edit .env and add your ConnectWise credentials:

# 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 Configuration:

• North America: https://api-na.myconnectwise.net
• Europe: https://api-eu.myconnectwise.net
• Australia: https://api-au.myconnectwise.net
• On-premise: Use your server URL

4. Start Services

Using the setup script (recommended):

chmod +x setup.sh
./setup.sh

Select option 1 to start the server.

Or manually with Docker Compose:

docker-compose up -d --build

Bridge available at: http://localhost:3002

5. Add Tool to OpenWebUI

1. Open OpenWebUI in your browser
2. Navigate to Settings → Admin Panel → Tools
3. Click "+ Create New Tool"
4. Copy the contents of connectwise_tools.py from this repository
5. Paste into the tool editor
6. Configure the bridge URL in the Valves section:
   • Docker: http://connectwise-mcp-bridge:3002
   • Local: http://localhost:3002
7. Click "Save"
8. Enable the ConnectWise Tools

6. Verify Installation

curl http://localhost:3002/health

Expected response:

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

Available Tools in OpenWebUI

Company Tools:

• get_companies() - Search companies with advanced filtering
• get_company() - Get specific company details
• get_company_sites() - Get sites/locations for a specific company
• get_company_types() - Get all company types for categorization
• get_company_statuses() - Get all company statuses

Ticket Tools:

• get_tickets() - Search tickets with conditions
• get_ticket() - Get specific ticket details
• get_ticket_notes() - Retrieve ticket notes and history
• get_ticket_tasks() - Get tasks/checklist items for a ticket
• get_ticket_schedules() - Get scheduled work for a ticket
• get_ticket_priorities() - Get all ticket priorities
• get_ticket_sources() - Get all ticket sources

Contact Tools:

• get_contacts() - Search contacts
• get_contact() - Get specific contact details
• get_contact_types() - Get all contact types

Sales Tools:

• get_opportunities() - Search sales opportunities

Agreement Tools:

• get_agreements() - Search agreements and contracts
• get_agreement_additions() - Get add-ons for a specific agreement

Time Entry Tools:

• get_time_entries() - Search time tracking data

Project Tools:

• get_projects() - Search projects

Activity Tools:

• get_activities() - Search activities and tasks

Member Tools:

• get_members() - Search team members

IT Asset Management Tools:

• get_configurations() - Search IT configurations/assets
• get_configuration() - Get specific configuration by ID
• get_configuration_types() - Get all configuration types

Finance & Billing Tools:

• get_invoices() - Search and retrieve invoices
• get_expense_entries() - Search expense entries
• get_billing_cycles() - Get all billing cycles

Service Desk Tools:

• get_service_boards() - Get all service boards
• get_board_statuses() - Get statuses for a specific board

All tools support pagination and ConnectWise condition syntax for advanced filtering.

Usage Examples

In OpenWebUI, communicate naturally:

General Queries:

• "Show me all open tickets for ACME Corp"
• "Find all companies with 'Tech' in their name"
• "Get details for ticket #12345"
• "List all opportunities with status 'Open'"
• "Show me time entries for this week"
• "Find contacts at Microsoft"
• "What projects are currently active?"
• "Show me all agreements expiring this month"

IT Asset Management:

• "Show me all servers for ACME Corp"
• "What configurations are assigned to ticket #5678?"
• "List all company sites for XYZ Corporation"
• "What configuration types do we have?"

Finance & Billing:

• "Show me all open invoices for this month"
• "What are the expense entries for John this week?"
• "List all billing cycles"
• "What add-ons are included in agreement #123?"

Service Desk:

• "What service boards do we have?"
• "Show me all statuses for the Help Desk board"
• "What tasks are on ticket #9999?"
• "Show scheduled work for ticket #1234"

Reference Data:

• "What company types are available?"
• "List all ticket priorities"
• "Show me all contact types"
• "What ticket sources do we track?"

The AI will automatically call the appropriate ConnectWise tool functions to complete your request.

ConnectWise API Conditions

ConnectWise uses a powerful condition syntax for filtering:

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

File Structure

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)

Management Commands

Using setup script:

./setup.sh

Options:

1. Start ConnectWise MCP Server
2. Stop ConnectWise MCP Server
3. Restart ConnectWise MCP Server
4. View logs
5. Check status
6. Update server
7. Clean up
8. Exit

Direct Docker commands:

# 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

Troubleshooting

Authentication Errors:

• Verify your Company ID, Public Key, and Private Key are correct
• Ensure the API member has appropriate permissions
• Check that the API URL matches your ConnectWise instance
• Generate new API keys if needed

Port Conflicts:

If port 3002 is already in use:

1. Edit .env file: MCP_PORT=3003
2. Edit docker-compose.yml: Update port mapping to 3003:3002 and environment PORT=3003
3. Restart: docker-compose down && docker-compose up -d --build
4. Update bridge URL in OpenWebUI Tool Valves

Bridge Connection Issues:

• Verify bridge is running: docker-compose ps
• Check bridge logs: docker-compose logs mcp-bridge
• Test health endpoint: curl http://localhost:3002/health
• Verify bridge URL in OpenWebUI Tool Valves settings:
  • Both in Docker: http://connectwise-mcp-bridge:3002
  • OpenWebUI local: http://localhost:3002

OpenWebUI Can't Connect:

• Ensure connectwise_tools.py is saved in OpenWebUI Tools
• Enable the ConnectWise Tools in OpenWebUI Settings
• Verify the bridge URL is correct in Valves settings
• Check Docker networks: docker network connect openwebui_network connectwise-mcp-bridge

Rate Limiting:

ConnectWise has API rate limits. If you encounter rate limiting:

• Reduce the pageSize parameter
• Add delays between requests
• Check ConnectWise API documentation for current limits

Security Best Practices

• Never commit .env file with real credentials to version control
• Use API-only member accounts with minimum required permissions
• Read-only access: This server is designed for read-only operations only
• Regularly rotate API credentials
• Limit IP access to ConnectWise API if possible
• Run bridge server in private network when possible
• Monitor API usage and set quotas

Development & Testing

Local Development:

MCP Server:

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

Bridge Server:

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

Testing API Endpoints:

Health check:

curl http://localhost:3002/health

Test search:

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
    }
  }'

Dependencies

Python packages (connectwise-mcp-server):

• mcp - Model Context Protocol framework
• fastmcp - Fast MCP server implementation
• httpx - Async HTTP client
• pydantic - Data validation

Node.js packages (mcp-bridge):

• express - Web server framework
• cors - CORS middleware

Resources

• ConnectWise Developer Network
• Model Context Protocol (MCP)
• OpenWebUI
• ConnectWise REST API Documentation

Important Notes

• This server provides READ-ONLY access to ConnectWise
• No write operations are implemented
• Designed for AI-assisted data retrieval and analysis
• Respects ConnectWise API rate limits
• Requires valid ConnectWise API credentials

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check existing documentation
• Review ConnectWise API documentation
• Check OpenWebUI documentation

License

MIT License - See LICENSE file for details

Version

Current Version: 1.1.0

Changelog

Version 1.1.0 (Enhanced Feature Set)

• Added IT Asset Management (configurations, configuration types, company sites)
• Added Finance & Billing (invoices, expense entries, billing cycles, agreement additions)
• Added Reference Data endpoints (company types/statuses, ticket priorities/sources, contact types)
• Added Service Desk Enhancements (service boards, board statuses, ticket tasks, ticket schedules)
• Total of 18 new read-only tools
• Enhanced documentation with new usage examples

Version 1.0.0 (Initial Release)

• Read-only access to ConnectWise Manage
• Support for companies, tickets, contacts, opportunities, agreements
• Time entries, projects, activities, and members
• Docker-based deployment
• OpenWebUI integration
• MCP bridge architecture
• Comprehensive documentation