
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
- 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_*, andinvoices_*. - Read-Only Enforcement: Middleware hides tools containing
create,update,delete,send,void, ordispatchin 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
- The user authenticates through the OAuth login flow.
- Claude connects to the hosted MCP server.
- FastMCP exposes the available CRM tools through domain-specific modules.
- Permission middleware determines which tools are visible to the agent.
- Claude uses the available tools to interact with the field-service CRM API.

05. Workflow

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 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.
Built with
Python, FastMCP, OAuth 2.0, REST and Railway.