HireNimbus home services MCP
Model Context Protocol server that connects AI assistants (Claude, ChatGPT, Gemini) to the HireNimbus home-services marketplace. Enables provider search, review aggregation, homeowner profile retrieval, and job booking — all through natural conversation.
Architecture
- Runtime: Python 3.10, FastAPI, FastMCP (
mcp1.26.0) - Transport: Streamable HTTP at
/mcp(rewritten from/for root-level MCP clients) - Deploy: AWS Lambda (arm64) via SAM + Docker container image; Mangum ASGI adapter
- Auth: Optional OAuth2 with JWT Bearer tokens; rate limiting per IP
Quick Start
# 1. Local secrets (gitignored — never commit)
cp local.config.example.json local.config.json
# Edit local.config.json with your values (or use .env — see .env.example)
# 2. SAM deploy overrides (ECR image URI — gitignored)
cp samconfig.local.toml.example samconfig.local.toml
# Edit samconfig.local.toml with your AWS ECR repository
# Build & deploy to AWS (local)
sam build && sam deploy --config-file samconfig.toml --config-file samconfig.local.toml
# Local development
pip install -r requirements.txt
uvicorn src.main:app --reloadGitHub Actions auto-deploy on main uses repository secrets (see internal deploy docs).
Configuration
Sensitive values live in local.config.json (gitignored) or environment variables. Copy local.config.example.json → local.config.json and fill in your values. Env vars always take precedence.
Public defaults remain in code for shared HireNimbus API endpoints (service.hirenimbus.com). URLs, tokens, and credentials must be set explicitly.
| Variable | Purpose | |---|---| | PROVIDERS_API | Provider search endpoint | | REVIEWS_API | Provider profile & reviews base URL | | BOOKING_API | Job creation endpoint | | COORDS_RESOLVE_API | City/text to coordinates resolution | | ZIP_RESOLVE_API | ZIP to city resolution | | SEND_BOOK_NOTIFICATION_API | SMS notification to homeowner | | SEND_JOB_TO_SLACK_API | Slack job alerts | | MCP_MONITOR_ENABLED | Post MCP auth/tool events to Slack (default: true) | | MCP_MONITOR_SLACK_CHANNEL | Slack channel for MCP monitor events (default: mcp-monitor) | | MCP_MONITOR_SLACK_API | Slack webhook for monitor events (defaults to SEND_JOB_TO_SLACK_API) | | OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET | Enable OAuth2 (both must be set) | | OAUTH_TOKEN_TTL | Access token lifetime in seconds (default: 3600) | | RATE_LIMIT_RPM | Requests per minute per IP (default: 60, 0 = off) | | PUBLIC_BASE_URL | Canonical public URL for OAuth issuer/audience |
---
MCP Tools
Implemented
search_providers
Search for home service professionals near a location.
| Parameter | Type | Required | Description | |---|---|---|---| | query | string | Yes | Service keyword — "plumber", "HVAC repair", "house cleaning" | | location | object | Yes | One of: {"text": "Alexandria, VA"}, {"zip": "22314"}, or {"lat": 38.8, "lng": -77.0} | | page | int | No | Pagination page (default: 1) | | limit | int | No | Results count (default: 6) |
Returns: providers list (name, slug, profile_url, rating, reviews_count, highlights) + resolved_location.
---
get_provider_details
Full profile for a single provider — bio, services, areas, hours, FAQ, photos.
| Parameter | Type | Required | Description | |---|---|---|---| | slug | string | Yes | Provider slug from search_providers results |
Returns: name, about, profile_url, profile_image_url, primary_service, services_offered, operational_areas, rating, reviews_count, hours_of_operation, faq, media_count, booking_supported.
---
get_provider_reviews
Aggregated reviews from Google, Yelp, Thumbtack, HomeAdvisor, and Nimbus.
| Parameter | Type | Required | Description | |---|---|---|---| | slug | string | Yes | Provider slug from search_providers results | | page | int | No | Pagination page (default: 1) | | page_size | int | No | Reviews per page, 1–10 (default: 5) |
Returns: reviews list (reviewer_name, date, rating, comment, source), stats (avg_rating, total_reviews), pagination, profile_url.
---
get_homeowner_profile
Returns the OAuth-linked homeowner's saved name, phone, and address. No parameters — identity comes from the JWT session.
Returns: connected, name, phone, address, source, tool_sourced_only.
---
create_booking
Submit a job request to a provider. Triggers instant SMS + Slack notification.
| Parameter | Type | Required | Description | |---|---|---|---| | serviceProviderSlug | string | Yes | Provider slug | | name | string | Yes | Homeowner full name | | phone | string | Yes | Homeowner phone | | job_description | string | Yes | Detailed description of work needed | | address | object | Yes | Must include address1, city, region, postalCode | | source | string | No | AI assistant name (default: "AI Assistant") | | location | object | No | Optional geocoding hint (same format as search_providers) |
Returns: status, job_id, message, details (notification delivery status).
---
Planned Tools
process_payment
Process a payment for a completed or quoted job through the Nimbus platform.
| Parameter | Type | Required | Description | |---|---|---|---| | job_id | string | Yes | Job identifier from create_booking | | amount | number | Yes | Payment amount in USD | | payment_method | string | Yes | One of: card_on_file, new_card, bank_transfer | | card_token | string | No | Required when payment_method is new_card |
Expected returns: status (success/pending/failed), transaction_id, receipt_url, message.
Typical flow: After a provider sends an estimate through Nimbus, the homeowner confirms the amount and the assistant processes payment via this tool. Supports saved payment methods and one-time card tokens.
---
approve_invoice
Review and approve (or reject) an invoice submitted by a service provider.
| Parameter | Type | Required | Description | |---|---|---|---| | invoice_id | string | Yes | Invoice identifier | | action | string | Yes | One of: approve, reject, request_revision | | notes | string | No | Homeowner comments or reason for rejection |
Expected returns: status, invoice_id, updated_amount, provider_notified, message.
Typical flow: The assistant retrieves pending invoices for the homeowner, presents line items and totals, and lets the homeowner approve, reject, or request changes — all conversationally.
---
schedule_appointment
Book a specific date and time slot with a provider for an existing or new job.
| Parameter | Type | Required | Description | |---|---|---|---| | serviceProviderSlug | string | Yes | Provider slug | | job_id | string | No | Existing job ID (if scheduling for an already-booked job) | | preferred_date | string | Yes | ISO 8601 date (2025-03-28) | | preferred_time_slot | string | Yes | One of: morning, afternoon, evening, or specific time like 14:00 | | notes | string | No | Special instructions (access codes, pet info, etc.) |
Expected returns: status (confirmed/pending_provider), appointment_id, confirmed_datetime, provider_notified, message.
Typical flow: After booking a job, the homeowner asks "Can I get this done Friday morning?" — the assistant checks provider availability and locks in a time slot, notifying both parties.
---
Typical Conversation Flow
User: "I need a plumber in Alexandria, VA"
-> search_providers(query="plumber", location={"text": "Alexandria, VA"})
User: "Tell me more about the first one"
-> get_provider_details(slug="...")
User: "What do people say about them?"
-> get_provider_reviews(slug="...")
User: "Book them for a leaking faucet"
-> get_homeowner_profile() # load saved name/phone/address
-> [confirm with user]
-> create_booking(...) # submit job + notify provider
User: "Schedule it for Friday morning"
-> schedule_appointment(...) # (planned)
User: "They sent an invoice — looks good, approve it"
-> approve_invoice(...) # (planned)
User: "Pay with my card on file"
-> process_payment(...) # (planned)License
This repository is source-available under the HireNimbus Demo Software License. It is provided for demo, reference, and evaluation purposes only. It is not open source and is not licensed for commercial, production, hosted, or competitive use.
