🏠 Hometeam MCP Server

Ask any AI about Black-owned businesses in South Florida. This is where the answers come from.

The Hometeam MCP server connects AI assistants to a curated, community-verified directory of Black-owned businesses across Miami-Dade, Broward, and Palm Beach counties. When someone asks Claude, "find me a Black-owned caterer in Broward County," this server provides the real, verified data behind the answer.

Built on the Model Context Protocol (MCP) — the open standard for connecting AI assistants to external data sources.

Published on the MCP Registry

This server is listed on the official MCP Registry as io.github.JajuanX/hometeam-directory.

Live endpoint: https://mcp.thehometeam.io/sse

Connect with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hometeam": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.thehometeam.io/sse"
      ]
    }
  }
}

Available tools

Rate limits

Connect to the live server

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hometeam": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://mcp.thehometeam.io/sse"
      ]
    }
  }
}

Restart Claude Desktop. Then ask:

• "Find me a Black-owned restaurant in Lauderhill"
• "What new businesses just joined Hometeam?"
• "I need someone to do box braids near Miramar"

HTTP endpoints

Rate limits

Quick test

# Service info
curl https://mcp.thehometeam.io/

# Health check
curl https://mcp.thehometeam.io/health

Verify on the registry

curl "https://registry.modelcontextprotocol.io/v0/servers/io.github.JajuanX%2Fhometeam-directory/versions/latest"

Local development

If you want to run the server locally (for development or contributing):

git clone https://github.com/juanx/hometeam-project-orange.git
cd hometeam-project-orange/hometeam/mcp-server
npm install
cp .env.example .env
# Edit .env — set MONGO_URI to the same database as the backend

# Run with stdio transport (for Claude Desktop local testing)
npm run start:local

# Run with HTTP/SSE transport (for remote access)
npm start

Claude Desktop config for local:

{
  "mcpServers": {
    "hometeam": {
      "command": "node",
      "args": ["/absolute/path/to/hometeam-mcp-server/server.js"],
      "env": {
        "MONGO_URI": "your_mongodb_connection_string"
      }
    }
  }
}

Important: Use the absolute path from pwd in the mcp-server directory. console.log is redirected to console.error because stdio transport uses stdout for JSON-RPC communication.

Available tools

The MCP server exposes 6 tools that AI assistants can call:

search_businesses

Search the directory by keyword, category, neighborhood, or county.

{
  "query": "jerk chicken",
  "county": "Broward",
  "limit": 5,
  "sort": "most_visited"
}

Returns matching businesses with name, category, neighborhood, rating, contact info, and Hometeam profile link.

get_business_details

Get everything about a specific business — hours, contact, social media, reviews, current specials.

{ "slug": "keishas-kitchen" }

Or search by name:

{ "name": "Keisha's Kitchen" }

Returns the full business profile including recent reviews, active specials, and community trust signals.

find_by_specialty

The smart search. Describe what you need in plain English.

{ "need": "someone to do box braids for my daughter's birthday", "location": "Miramar" }

{ "need": "tax preparation for my small business", "location": "Palm Beach" }

{ "need": "a barber who can do a fresh fade", "location": "Overtown" }

Maps natural language to categories and searches intelligently. This is the tool most AI assistants reach for first.

list_categories

Returns all business categories in the directory. No parameters needed.

Categories: Restaurants & Food, Hair & Beauty, Health & Wellness, Home Services, Professional Services, Retail & Shopping, Auto Services, Education & Tutoring, Events & Entertainment, Fitness & Training, Technology & Media, Real Estate, Childcare & Family, Arts & Creative.

list_neighborhoods

Returns South Florida neighborhoods, optionally filtered by county.

{ "county": "Broward" }

Covers 29+ neighborhoods across Miami-Dade, Broward, and Palm Beach counties.

get_latest_draft_class

Returns the most recent Draft Class — the newest businesses to join Hometeam. No parameters needed.

Hometeam drafts new businesses monthly through community events. This tool lets AI assistants answer "what's new?" questions with real, timely data.

How it works

User asks AI: "Find me a Black-owned caterer in Broward"
         │
         ▼
AI assistant sees Hometeam MCP tools are available
         │
         ▼
AI calls search_businesses({ query: "caterer", county: "Broward" })
         │
         ▼
Hometeam MCP server queries the live MongoDB database
         │
         ▼
Returns real business data: name, location, rating, contact, hours
         │
         ▼
AI presents the answer to the user with Hometeam attribution
         │
         ▼
User visits the business. Community grows.

The data is always live — not a cached snapshot. When a business updates their hours or posts a special, the MCP server reflects it immediately.

Project structure

mcp-server/
├── server.js                  # Entry point (stdio transport — local/Claude Desktop)
├── httpServer.js              # HTTP/SSE transport (deployed/remote access)
├── config/
│   └── db.js                  # MongoDB connection
├── models/                    # Mongoose schemas (read-only, shared with backend DB)
│   ├── Business.js
│   ├── Category.js
│   ├── Neighborhood.js
│   ├── Review.js
│   ├── Event.js
│   ├── DraftClass.js
│   └── McpUsage.js
├── tools/                     # MCP tool definitions + handlers
│   ├── searchBusinesses.js
│   ├── getBusinessDetails.js
│   ├── findBySpecialty.js
│   ├── listCategories.js
│   ├── listNeighborhoods.js
│   └── getLatestDraftClass.js
├── middleware/
│   └── apiKeyAuth.js          # API key validation (paid tier — coming soon)
├── utils/
│   └── logUsage.js            # Query analytics logger
├── scripts/
│   └── release.js             # Semantic version release script
└── .env.example

Transport modes

Stdio (local)

For Claude Desktop and local development. Communicates via stdin/stdout using JSON-RPC.

npm run start:local

Critical: All logging uses console.error, not console.log. Stdout is reserved for the MCP protocol. Any console.log output corrupts the JSON-RPC stream and crashes the connection.

HTTP/SSE (deployed)

For production and remote AI agents. Express server with Server-Sent Events.

npm start
# Starts on PORT (default 3001, Heroku assigns dynamically)

Endpoints:

Developer workflow

Coding conventions

Defined in AGENTS.md at the project root (shared with the backend). Key rules:

• ES Modules — import/export with .js extensions on all relative imports
• Async/await throughout
• console.error only — never console.log (breaks stdio transport)
• Models — export default, read-only versions of backend schemas
• Tools — each tool in its own file, exports schema + handler

Adding a new MCP tool

1. Create mcp-server/tools/myNewTool.js with a schema and handler export:

   server.ts

   Copy

   export const myNewToolSchema = {
     description: 'What this tool does — written for an AI to understand when to use it',
     inputSchema: {
       type: 'object',
       properties: {
         param1: { type: 'string', description: 'What this parameter means' },
       },
       required: ['param1'],
     },
   };
   
   export const myNewToolHandler = async (args) => {
     // Query MongoDB, format results
     return { success: true, data: { args } };
   };
   

2. Register it in mcp-server/tools/index.js:

   server.ts

   Copy

   import { myNewToolHandler, myNewToolSchema } from './myNewTool.js';