← Back

Python MCP Server Connecting Claude to a Field-Service CRM

A hosted, OAuth-protected MCP server in Python that lets a home-services business ask Claude about customers, jobs, invoices and leads, with write actions hidden unless allowed.

Python Automation
Works with
  • Python
  • FastMCP
  • OAuth 2.0
  • REST API
  • Railway
  • Claude

Project Overview

This project connects Claude to Housecall Pro, enabling a home-services business to ask questions about customers, jobs, invoices, and leads through an MCP server built with Python and FastMCP.

Technology: Python, FastMCP, OAuth 2.0, REST API, Railway, Claude

01. The Problem

The business wanted to interact with its field-service data through Claude and perform permitted actions without giving the AI direct access to the raw database.

02. The Solution

A Python MCP server was developed to expose the Housecall Pro REST API through approximately 20 domain modules, covering customers, jobs, estimates, invoices, leads, employees, scheduling, webhooks, and more.

The server is hosted on Railway and connects to claude.ai.

03. Key Features

  • OAuth 2.0 Authentication: Uses GitHub as the OAuth provider, with authentication redirecting back to claude.ai.
  • Domain-Specific Tools: Organizes tools into namespaces such as customers_*, jobs_*, and invoices_*.
  • Read-Only Enforcement: Middleware hides tools containing create, update, delete, send, void, or dispatch in their names unless explicitly allowed.
  • REST API Integration: Exposes field-service functionality through a unified FastMCP application.
  • Hosted Deployment: Runs on Railway for connection to Claude.

04. How It Works

  1. The user authenticates through the OAuth login flow.
  2. Claude connects to the hosted MCP server.
  3. FastMCP exposes the available CRM tools through domain-specific modules.
  4. Permission middleware determines which tools are visible to the agent.
  5. Claude uses the available tools to interact with the field-service CRM API.
The server entry point: GitHub OAuth in front, one FastMCP app, and each domain module (customers, jobs, estimates, invoices, leads, employees) mounted under its own namespace.

05. Workflow

04438c4be6f30a7d6dd70154.png

06. Implementation

The server entry point mounts the CRM domain modules under one FastMCP application. Each module handles a specific area of the field-service API, while OAuth authentication and permission middleware control access to the available tools.

The repository: one Python module for each area of the field-service API, plus a Procfile for deployment on Railway. The commit messages are blurred.

The repository contains separate Python modules for the different API domains and a Procfile for Railway deployment.

07. Outcome

The solution provides Claude with a structured interface to field-service CRM data, with OAuth authentication, domain-specific tool namespaces, and protocol-level controls over which actions are exposed to each agent.

Python, FastMCP, OAuth 2.0, REST and Railway.