---
title: FixMyNeighborhood MCP Server
emoji: 🏙️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: "6.0.0"
app_file: app.py
pinned: false
tags:
  - building-mcp-track-enterprise
  - building-mcp-track-consumer
  - building-mcp-track-customer
  - building-mcp-track-creative
  - mcp-server
  - tools
---

# FixMyNeighborhood MCP Server

[![MCP 1st Birthday Hackathon](https://img.shields.io/badge/%F0%9F%8E%82%20MCP%201st%20Birthday-Hackathon-ff69b4)](https://huggingface.co/MCP-1st-Birthday)
[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/MCP-1st-Birthday/fixmyneighborhood-mcp-server)
[![Gradio](https://img.shields.io/badge/Gradio-6.0-orange.svg)](https://gradio.app/)
[![MCP](https://img.shields.io/badge/MCP-tools-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP (Model Context Protocol) tool server providing NYC infrastructure data for AI agents. Built for the [MCP 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday).

## Demo

[Watch Demo Video](https://drive.google.com/file/d/1kyrgx4EtY5mA7NJxFF9r6E2hofcEGriY/view?usp=sharing)

## Social Media

[X Post](https://x.com/livewiring/status/1994825595163975848)

## MCP Endpoints

| Transport | URL |
|-----------|-----|
| **SSE** | `https://mcp-1st-birthday-fixmyneighborhood-mcp-server.hf.space/gradio_api/mcp/sse` |
| **HTTP** | `https://mcp-1st-birthday-fixmyneighborhood-mcp-server.hf.space/gradio_api/mcp/` |

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `geo_search_address` | Reverse geocode lat/lon to NYC address (real data via Photon API) | `lat`, `lon` |
| `validate_address` | Validate NYC address and detect borough (real data via Photon API) | `address` |
| `cityinfra_lookup_asset` | Look up city infrastructure records (real data via NYC Open Data) | `address`, `asset_type` |
| `get_nearby_reports` | Find similar 311 reports nearby (real data via NYC 311 Open Data) | `address`, `issue_type`, `radius_blocks` |
| `weather_get_current` | Get current weather + hazard assessment (real data via Weather.gov) | `lat`, `lon` |
| `get_department_info` | Get NYC department contact info and SLA targets (real data via NYC 311 SLA) | `department_code` |
| `pdf_generate_report` | Generate real PDF report (via ReportLab) | `issue_type`, `address`, `urgency`, `description` |
| `sendgrid_send_email` | Send email via Resend API (test mode - routes to test sink) | `to`, `subject`, `body`, `api_key`, `from_email`, `report_id` |

## Use with Claude Desktop

Add to your Claude Desktop config:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "fixmyneighborhood": {
      "url": "https://mcp-1st-birthday-fixmyneighborhood-mcp-server.hf.space/gradio_api/mcp/sse"
    }
  }
}
```

Restart Claude Desktop. Then try:

> "There's a pothole at coordinates 40.7580, -73.9855. Can you look up the address and find out which department handles road issues?"

## Use with MCP Inspector

Test the server with the official MCP Inspector:

```bash
npx @anthropic-ai/mcp-inspector https://mcp-1st-birthday-fixmyneighborhood-mcp-server.hf.space/gradio_api/mcp/sse
```

## Use with FixMyNeighborhood App

This MCP server powers the [FixMyNeighborhood App](https://huggingface.co/spaces/MCP-1st-Birthday/fixmyneighborhood-app), a full AI agent application for reporting city infrastructure issues.

## Local Development

```bash
# Clone the repo
git clone https://huggingface.co/spaces/MCP-1st-Birthday/fixmyneighborhood-mcp-server

# Install dependencies
pip install -r requirements.txt

# Run with MCP enabled
python app.py
```

Local MCP endpoint: `http://localhost:7860/gradio_api/mcp/sse`

## Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                      Gradio MCP Server (8 Tools)                 │
├──────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
│  │ geo_search      │  │ validate        │  │ cityinfra       │   │
│  │ _address 🌐     │  │ _address 🌐     │  │ _lookup_asset🌐 │   │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
│  │ get_nearby      │  │ weather_get     │  │ get_department  │   │
│  │ _reports 🌐     │  │ _current 🌐     │  │ _info 🌐        │   │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘   │
│  ┌─────────────────┐  ┌─────────────────┐                        │
│  │ pdf_generate    │  │ sendgrid        │   🌐 = Real API       │
│  │ _report 🌐      │  │ _send_email 🌐  │                        │
│  └─────────────────┘  └─────────────────┘                        │
├──────────────────────────────────────────────────────────────────┤
│                   /gradio_api/mcp/sse (SSE)                      │
│                   /gradio_api/mcp/ (HTTP)                        │
└──────────────────────────────────────────────────────────────────┘
              │                    │                  │
              ▼                    ▼                  ▼
        Claude Desktop      MCP Inspector      FixMyNeighborhood App
```

### Real API Integrations

| Tool | API Source | Free Tier |
|------|-----------|-----------|
| `geo_search_address` | Photon API (OpenStreetMap) | Unlimited (500ms rate limit) |
| `validate_address` | Photon API (OpenStreetMap) | Unlimited (500ms rate limit) |
| `cityinfra_lookup_asset` | NYC Open Data (DOT Pothole Work Orders) | Unlimited |
| `get_nearby_reports` | NYC 311 Open Data | Unlimited |
| `weather_get_current` | Weather.gov (NOAA) | Unlimited |
| `get_department_info` | NYC 311 SLA Data | Unlimited |
| `pdf_generate_report` | ReportLab (local generation) | N/A |
| `sendgrid_send_email` | Resend API (test sink: `delivered@resend.dev`) | Safe demo mode |

## Complete Report Flow

The server supports a production-ready flow with safety guardrails:

```
1. pdf_generate_report()  →  Creates PDF, returns report_id (e.g., "FMN-20251127050500")
2. sendgrid_send_email(report_id="FMN-20251127050500")  →  Attaches PDF to email
                                                        →  Routes to test sink (delivered@resend.dev)
```

**Safety Features:**
- All emails route to `delivered@resend.dev` (Resend test sink)
- From address uses `onboarding@resend.dev` (no domain verification needed)
- Real Resend API is exercised, but no emails reach municipal inboxes

## Hackathon Track

**Track 1: Building MCP** - This server demonstrates how to build MCP tools with Gradio that can be used by any MCP-compatible client (Claude Desktop, AI agents, etc.).