How do I install Nimbus?

Nimbus supports both local and remote installation. For local use, install it via the provided package manager and add the configuration to your AI app. For remote access, add the server URL to your MCP configuration.

What credentials does Nimbus need?

Nimbus requires the following credentials or environment variables: PROVIDERS_API, REVIEWS_API, BOOKING_API, COORDS_RESOLVE_API, ZIP_RESOLVE_API, SEND_BOOK_NOTIFICATION_API, SEND_JOB_TO_SLACK_API, MCP_MONITOR_ENABLED, MCP_MONITOR_SLACK_CHANNEL, MCP_MONITOR_SLACK_API, OAUTH_TOKEN_TTL, RATE_LIMIT_RPM, PUBLIC_BASE_URL. You can find setup instructions on the server detail page.

What AI apps work with Nimbus?

Nimbus uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Nimbus MCP Server

by Ivan Myshakivskyi

Developer ToolsUse Caution4.0LocalRemoteNew

Free

Find and book verified local home service professionals through AI agents.

About

Find and book verified local home service professionals through AI agents.

Remote endpoints: streamable-http: https://mcp.hirenimbus.com/mcp

Security Report

4.0

Use Caution4.0High Risk

This MCP server implements OAuth2 with phone/OTP authentication for a home-services marketplace, with generally sound architecture but several security concerns. Key issues include: (1) unvalidated external API calls that could be exploited for SSRF or data exfiltration, (2) broad file system and network permissions without strict bounds, (3) sensitive data (phone numbers, addresses, profiles) logged in plaintext, and (4) missing input validation on critical booking parameters. While the OAuth/PKCE implementation is solid and credentials are properly managed, these vulnerabilities create moderate risk for data leakage and unauthorized actions. Supply chain analysis found 4 known vulnerabilities in dependencies (0 critical, 1 high severity).

3 files analyzed · 14 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

system_info

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Provider search endpointOptional

Environment variable: PROVIDERS_API

Provider profile & reviews base URLOptional

Environment variable: REVIEWS_API

Job creation endpointOptional

Environment variable: BOOKING_API

City/text to coordinates resolutionOptional

Environment variable: COORDS_RESOLVE_API

ZIP to city resolutionOptional

Environment variable: ZIP_RESOLVE_API

SMS notification to homeownerOptional

Environment variable: SEND_BOOK_NOTIFICATION_API

Slack job alertsOptional

Environment variable: SEND_JOB_TO_SLACK_API

Post MCP auth/tool events to Slack (default: true)Optional

Environment variable: MCP_MONITOR_ENABLED

Slack channel for MCP monitor events (default: mcp-monitor)Optional

Environment variable: MCP_MONITOR_SLACK_CHANNEL

Slack webhook for monitor events (defaults to SEND_JOB_TO_SLACK_API)Optional

Environment variable: MCP_MONITOR_SLACK_API

Access token lifetime in seconds (default: 3600)Optional

Environment variable: OAUTH_TOKEN_TTL

Requests per minute per IP (default: 60, 0 = off)Optional

Environment variable: RATE_LIMIT_RPM

Canonical public URL for OAuth issuer/audienceOptional

Environment variable: PUBLIC_BASE_URL

How to Install & Connect

Available as Local & Remote

This plugin can run on your machine or connect to a hosted endpoint. during install.

Documentation

View on GitHub

From the project's GitHub README.

HireNimbus MCP Server

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 (mcp 1.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 --reload

GitHub 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.