Perfex Mcp Server

Perfex CRM MCP Server

A Model Context Protocol (MCP) server for Perfex CRM. Connect Claude, Cursor, or any MCP-compatible AI client directly to your CRM data.

> Ask Claude: "Show me all unpaid invoices" or "Create an estimate for client Acme Corp" — and it queries your Perfex CRM in real-time.

Quick Start

1. Download mcp_connector.zip from Releases
2. Upload in Perfex CRM: Setup > Modules > Upload Module
3. Activate the module
4. Copy .well-known/ folder to your Perfex webroot (required for OAuth discovery)
5. Connect Claude: add your server URL as a custom connector

Features

• 12 MCP Tools for Clients, Invoices, Estimates, and MainWP Sites
• Read & Write — search, view details, and create new records
• OAuth 2.1 — native authentication with Claude.ai, Claude Desktop, and Claude Code (PKCE, DCR, token refresh)
• Bearer Token Auth — manual token creation for API access
• Safety Annotations — all tools annotated with readOnlyHint / destructiveHint
• Audit Log — every tool call logged with staff context and IP anonymization (GDPR)
• Streamable HTTP — works remotely over HTTPS
• Admin UI — manage tokens and view audit logs in Perfex
• No extra license needed — uses Perfex internal models, not the REST API module

Available Tools

| Tool | Type | Description | |------|------|-------------| | search_clients | Read | Search clients by name, company, or email | | get_client | Read | Get client details with contacts and linked sites | | create_client | Write | Create a new client | | search_invoices | Read | Search invoices by client, status, date range | | get_invoice | Read | Get invoice with line items and payments | | create_invoice | Write | Create invoice with items and tax | | search_estimates | Read | Search estimates by client and status | | get_estimate | Read | Get estimate with line items | | create_estimate | Write | Create estimate with items and tax | | list_client_sites | Read | List MainWP sites for a client | | get_site_details | Read | Get site details (plugins, versions, maintenance) | | create_site | Write | Link a new site to a client * |

\* MainWP tools require the MainWP Connect module. If not installed, the other 9 tools work normally.

Requirements

• Perfex CRM 3.0+
• PHP 8.1+
• HTTPS with a valid SSL certificate

Installation

Option A: Upload ZIP (Recommended)

1. Download mcp_connector.zip from the latest release
2. In Perfex CRM, go to Setup > Modules
3. Click Upload Module and select the ZIP file
4. Activate the module

Option B: Manual / Developer Setup

cd /path/to/perfex/modules
git clone https://github.com/stoffl6781/perfex-mcp-server.git mcp_connector
cd mcp_connector
composer install --no-dev

Activate in Setup > Modules.

OAuth Discovery (Required)

Copy the .well-known/ folder from the module to your Perfex webroot:

cp -R modules/mcp_connector/.well-known /path/to/perfex/.well-known

This serves the OAuth Authorization Server Metadata at /.well-known/oauth-authorization-server, which MCP clients need to discover your auth endpoints.

Authentication

Option 1: OAuth 2.1 (Claude.ai, Claude Desktop, Cursor)

The module implements full OAuth 2.1 with:

• Dynamic Client Registration (RFC 7591) — clients register automatically
• PKCE (S256) — secure authorization code flow
• Token refresh — automatic token renewal

Connect via Claude.ai:

1. Go to Settings > Connectors > Add Custom Connector
2. Enter your server URL: https://your-crm.com/mcp_connector/mcp_server
3. Click Add — Claude handles the OAuth flow automatically
4. Sign in with your Perfex staff email and password when prompted

Connect via Claude Desktop:

1. Go to Settings > Connectors
2. Add remote connector with URL: https://your-crm.com/mcp_connector/mcp_server

Option 2: Bearer Token (API / Claude Code CLI)

For programmatic access or Claude Code:

1. Go to Setup > MCP Connector in Perfex admin
2. Create a token with desired permissions
3. Use the token:

claude mcp add perfex-crm \
  --transport streamable-http \
  --url https://your-crm.com/mcp_connector/mcp_server \
  --header "Authorization: Bearer mcp_your_token_here"

Example Usage

> "Show me all clients in my CRM"

> "Which invoices are overdue?"

> "Create an invoice for client 42: Web Development, 10 hours at 120 EUR, tax MwSt|20.00"

> "List all MainWP sites for client Acme Corp"

Security

| Feature | Implementation | |---------|---------------| | OAuth 2.1 | PKCE (S256), DCR, token refresh, 24h expiry | | Token Storage | SHA-256 hash (plaintext shown once) | | Transport | HTTPS required (HTTP rejected with 421) | | Rate Limiting | 60 req/min per token (atomic SQL) | | Permissions | Per-token: tool groups + read/write level | | Safety Annotations | All tools annotated (readOnlyHint / destructiveHint) | | Delete Protection | No delete operations by design | | Audit Log | Staff context + anonymized IP (GDPR) | | Data Exposure | No IBAN, passwords, or API keys in responses |

Tax Format

Perfex CRM uses pipe-separated tax format: "TaxName|TaxRate"

Examples: "MwSt|20.00" (AT), "VAT|19.00" (DE), "USt|7.00" (reduced)

Architecture

MCP Client                    Perfex CRM Server
┌──────────────┐              ┌──────────────────────┐
│  Claude.ai / │  OAuth 2.1   │  /.well-known/       │
│  Desktop /   │◄───────────►│  oauth-authorization  │
│  Code /      │              │  -server              │
│  Cursor      │  HTTPS       │                       │
│              │◄───────────►│  /mcp_connector/       │
└──────────────┘  Bearer      │  mcp_server           │
                  Token       │       │                │
                              │  ┌────▼─────────────┐ │
                              │  │ McpAuth (PSR-15)  │ │
                              │  └────┬─────────────┘ │
                              │  ┌────▼─────────────┐ │
                              │  │ MCP SDK (12 Tools)│ │
                              │  └────┬─────────────┘ │
                              │  ┌────▼─────────────┐ │
                              │  │ Perfex Models     │ │
                              │  │ (Direct DB)       │ │
                              │  └──────────────────┘ │
                              └──────────────────────┘

Roadmap

v1.1 (Current)

• Clients, Invoices, Estimates, MainWP Sites (search, get, create)
• OAuth 2.1 + Bearer Token auth
• Safety annotations, audit logging

Planned

• Update operations for existing records
• Projects, Tasks, Time tracking, Leads
• Invoice PDF as MCP Resource
• MCP Prompts (pre-built workflows)

Contributing

Contributions welcome! Please open an issue first to discuss changes.

License

MIT — see [LICENSE](LICENSE)

Author

Christoph Purin — purin.at

Built with Claude Code.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stoffl6781
• Source: stoffl6781/perfex-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.