CrewAI MCP Neighborhood Guide Agents

A multi-agent system that generates hyper-local neighborhood guides with real estate data, crime statistics, demographics, and lifestyle insights — powered by CrewAI, Google Gemini, and 13 production MCP servers from the Vinkius AI Gateway.

The Opportunity in Hyper-Local Content

Every day, thousands of people search for "what is it like to live in [neighborhood]", "is [neighborhood] safe", or "cost of living in [city]". These queries represent some of the highest-intent traffic in digital real estate — people actively considering a move or an investment.

The content that currently ranks for these terms is remarkably weak. Most neighborhood guides are written by real estate agencies recycling the same generic paragraphs, or by content farms that have never visited the area they are describing. There is no real crime data, no actual housing market metrics, no sentiment from people who actually live there.

This project demonstrates what becomes possible when AI agents have direct access to real data sources. Three specialized agents collaborate to produce a comprehensive neighborhood guide that includes verified property prices from Zillow, crime statistics from the Department of Justice, demographic data from the US Census, weather patterns, local venue recommendations from Foursquare and TripAdvisor, and actual resident opinions from X/Twitter and Reddit — all gathered in real time through the Model Context Protocol (MCP).

How It Works

The system operates as a sequential pipeline of three agents, each connected to a curated set of MCP servers hosted on the Vinkius AI Gateway.

Phase 1 — Geospatial Data Collection

The first agent builds a quantitative profile of the neighborhood. It connects to six MCP servers:

• Zillow for property listings, Zestimate values, and market trends
• Google Maps for schools, transit stops, grocery stores, parks, and distances
• US Census (Housing) for homeownership rates, median rent, and housing values
• US Census (Population) for demographics, age distribution, and diversity metrics
• DOJ Crime Data for violent and property crime rates with comparison to national averages
• Open-Meteo for historical weather patterns and climate classification

The result is a data-dense profile with every metric attributed to its source. The agent is instructed to never fabricate data — gaps are explicitly noted.

Phase 2 — Local News and Community Sentiment

The second agent investigates the human side of the neighborhood. It connects to five MCP servers:

• NewsAPI for recent articles about the area — development projects, zoning changes, major events
• X/Twitter for what residents are currently saying about their neighborhood
• Exa AI for semantic search across Reddit, local forums, and blog posts
• Foursquare for popular local venues — the restaurants, cafes, and bars that define the area's character
• TripAdvisor for visitor reviews and local experience ratings

The output identifies trends: is the neighborhood gentrifying? Is new transit driving property values up? What are the recurring complaints from residents? All supported by direct quotes and source attribution.

Phase 3 — Lifestyle Guide with Local SEO

The third agent receives all data and writes the final guide. Before writing, it uses two MCP servers for keyword research:

• SEMrush for local keyword difficulty, search volume, and competitor analysis
• SerpAPI for current SERP features and ranking landscape

The result is a ~3,000-word guide that reads like it was written by a knowledgeable local — someone who can tell you the median home price, the safest streets, the best coffee shop, and what the weekend farmers market is like, all backed by data.

Why MCP Servers Make This Possible

Building this system without MCP would require custom integrations for 13 different APIs — each with its own authentication flow, rate limiting strategy, response format, and maintenance burden. For a solo developer or a small team, that is weeks of engineering before writing a single line of agent logic.

The Vinkius AI Gateway eliminates this entirely. It provides a managed registry of over 2,600 production-ready MCP servers that AI agents connect to through a single, standardized protocol. Each server is an authenticated SSE endpoint:

https://edge.vinkius.com/<your_token>/mcp

This project uses 13 of those 2,600+ servers. But the same architecture can be extended to any domain:

• Commercial real estate analysis adding CoStar, LoopNet, and municipal GIS data
• International coverage adding Idealista (Europe), Rightmove (UK), or Domain (Australia)
• Investment analysis adding FRED economic data, SEC filings, and Bloomberg terminals
• Vacation rental research adding Airbnb and Booking.com market data

Each new data source is a one-line configuration change. The architecture scales without additional engineering.

MCP Servers Used in This Project

This project connects to 13 MCP servers, grouped by agent specialization:

| MCP Server | Agent | Data Provided | |---|---|---| | zillow-mcp | Geospatial Analyst | Property listings, Zestimate values, market trends | | google-maps-mcp | Geospatial Analyst | Schools, transit, amenities, distances | | us-census-housing-home-values-rent-real-estate-data-mcp | Geospatial Analyst | Housing values, rent, homeownership rates | | us-census-population-demographics-age-diversity-mcp | Geospatial Analyst | Population, demographics, diversity | | doj-ncvs-crime-data-mcp | Geospatial Analyst | Crime statistics (DOJ) | | open-meteo-weather-forecast-mcp | Geospatial Analyst | Weather, climate averages | | newsapi-mcp | Local Journalist | Breaking news, local articles | | x-twitter-mcp | Local Journalist | Resident opinions, community trends | | exa-ai-mcp | Local Journalist | Reddit, forums, semantic search | | foursquare-mcp | Local Journalist | Restaurants, bars, local venues | | tripadvisor-mcp | Local Journalist | Attractions, reviews, experiences | | semrush-mcp | Lifestyle Writer | Local keyword research, SERP analysis | | serpapi-mcp | Lifestyle Writer | SERP features, competitor content |

All 13 servers are hosted on the Vinkius AI Gateway. This project uses a fraction of what is available — browse the full catalog of 2,600+ production-ready MCP servers at vinkius.com/en/categories.

Getting Started

Prerequisites

• Python 3.11+
• A Google Gemini API key (free tier is sufficient)
• MCP server endpoints from the Vinkius AI Gateway

Installation

git clone https://github.com/vinkius-labs/crewai-mcp-neighborhood-guide-agents.git
cd crewai-mcp-neighborhood-guide-agents

python -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows

pip install -e .

Configuration

cp .env.example .env

Open .env and configure:

1. Your Gemini API key from Google AI Studio
2. Your Vinkius MCP URLs — deploy the MCP servers you need from the Vinkius AI Gateway marketplace, then copy each server's SSE endpoint URL

Usage

# Validate your configuration
neighborhood-guide validate

# Generate a neighborhood guide
neighborhood-guide generate "Williamsburg" "New York" "NY"

# The guide is saved to output/williamsburg-new-york-neighborhood-guide.md

Generated Guide Structure

| Section | Content | |---|---| | Quick Facts Box | Population, median price, safety score, walkability | | Overview | Character, vibe, who lives here | | Real Estate Market | Prices, trends, investment outlook with data tables | | Safety and Crime | Statistics with city/national comparison | | Schools and Education | Nearby schools with ratings | | Things to Do | Restaurants, parks, nightlife from Foursquare/TripAdvisor | | Transportation | Transit options, commute times | | Demographics and Cost of Living | Income, diversity, living costs | | What Residents Say | Real quotes from X/Twitter and Reddit | | Neighborhood Outlook | Development trends, investment signals | | FAQ | 5 common questions for People Also Ask |

Technical Details

• Framework: CrewAI with Flows and @CrewBase decorators
• LLM: Google Gemini 2.0 Flash (free tier, ~15 RPM)
• State Management: Pydantic models for type-safe data flow between agents
• MCP Integration: Native CrewAI mcps= field with SSE transport to Vinkius AI Gateway
• CLI: Typer with Rich console output
• Rate Limiting: max_rpm=10 per agent to stay within Gemini free tier limits

FAQ

What is MCP?

The Model Context Protocol is an open standard for connecting AI systems to external tools and data sources. It provides a unified interface that works across agent frameworks. See modelcontextprotocol.io.

Can I use this for neighborhoods outside the US?

The architecture supports any location. The US Census and DOJ Crime Data MCPs are US-specific, but you can substitute them with local equivalents. The Vinkius AI Gateway includes MCP servers for Idealista (Europe), weather services for multiple countries, and location data via Google Maps which is global. Browse the full catalog of 2,600+ MCP servers at vinkius.com/en/categories.

Can I use a different LLM?

Yes. CrewAI supports OpenAI, Anthropic, Mistral, and any LiteLLM-compatible model. Change the LLM configuration in crew.py.

How do I add more MCP servers?

Add the server to config/mcp_servers.yaml, set the URL in .env, and it becomes automatically available. The Vinkius AI Gateway offers 2,600+ MCP servers across every major category — explore the full catalog.

Contributing

We welcome contributions from the community. Please read the Contributing Guide before submitting a pull request.

License

MIT — see LICENSE.

Built by Vinkius Labs with CrewAI and the Vinkius AI Gateway.