# NYC 311

> NYC 311 is an open-source MCP server for legal and government. Answers about reporting problems to NYC 311 and your district's reports, from City data. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux
- **Website:** https://betanyc.github.io/nyc-311-mcp/
- **Repository:** https://github.com/betanyc/nyc-311-mcp
- **MCP Registry name:** io.github.BetaNYC/nyc-311-mcp
- **Categories:** legal and government, analytics and data
- **Listing updated:** 2026-11-14

## About

Built by BetaNYC, this server answers from New York City's own 311 data and says where each answer came from. Describe a problem in plain words and how_to_report finds the City's 311 article, the agency and the ways to report it; draft_311_report writes a short report you can paste, and the server never files anything with 311 for you. If a description sounds dangerous, such as smoke next door, the first line tells you to call 911.

District questions come from BoardStat, which BetaNYC builds nightly from NYC Open Data: top problems, trends, how quickly agencies close requests and what is still open, for a community or Council district. It also rebuilds the monthly reports required by Local Law 47 of 2005, labelled as BetaNYC rebuilds rather than official ones, and covers the 311 calendar, such as alternate side parking.

Version 1.3.0 has 24 tools and caches about 85 MB of public data. A free NYC 311 API key unlocks the calendar, status, request lookup and reporting tools; the district tools work without it. Every answer ends with an emergency and accuracy notice.

## Features

- **Reporting guidance:** Finds the City's 311 article, agency and reporting routes for a problem.
- **District statistics:** Eleven tools use BoardStat for community and Council districts.
- **Local Law 47 reports:** Rebuilds of the monthly 311 reports, marked as unofficial.
- **Calendar and alerts:** Covers the 311 calendar and status alerts such as alternate side parking.
- **Request lookup:** Looks up a 311 request with its status in words.
- **Source tracking:** about_data explains where each answer's data comes from.

## Good for

- Work out how to report a pothole and which agency handles it
- See what a community district reports most
- Compare how fast agencies close requests
- Check whether alternate side parking is on today
- Look up the status of a 311 request

## Install

### Claude Code (Terminal)

```sh
claude mcp add nyc-311-mcp --env NYC_311_API_KEY='<NYC_311_API_KEY>' --env SOCRATA_APP_TOKEN='<SOCRATA_APP_TOKEN>' -- npx -y @betanyc/nyc-311-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "nyc-311-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@betanyc/nyc-311-mcp"
      ],
      "env": {
        "NYC_311_API_KEY": "<NYC_311_API_KEY>",
        "SOCRATA_APP_TOKEN": "<SOCRATA_APP_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "nyc-311-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@betanyc/nyc-311-mcp"
      ],
      "env": {
        "NYC_311_API_KEY": "<NYC_311_API_KEY>",
        "SOCRATA_APP_TOKEN": "<SOCRATA_APP_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "nyc-311-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@betanyc/nyc-311-mcp"
      ],
      "env": {
        "NYC_311_API_KEY": "<NYC_311_API_KEY>",
        "SOCRATA_APP_TOKEN": "<SOCRATA_APP_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "nyc-311-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@betanyc/nyc-311-mcp"
      ],
      "env": {
        "NYC_311_API_KEY": "<NYC_311_API_KEY>",
        "SOCRATA_APP_TOKEN": "<SOCRATA_APP_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "nyc-311-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@betanyc/nyc-311-mcp"
      ],
      "env": {
        "NYC_311_API_KEY": "<NYC_311_API_KEY>",
        "SOCRATA_APP_TOKEN": "<SOCRATA_APP_TOKEN>"
      }
    }
  }
}
```

## Tools

- `how_to_report`: Finds the City's 311 article, agency and reporting routes for a described problem.
- `draft_311_report`: Writes a short report for you to paste; it does not file anything.
- `whats_changed`: Says what changed in the server.
- `about_betanyc`: Says who built the server and where to report bugs or request features.
- `about_data`: Says where each answer's data comes from and how current it is.

## FAQ

### Does it file reports with 311?

No. It only drafts text for you to paste.

### Do I need an API key?

A free NYC 311 Public API key is needed for calendar, status, request lookup and reporting tools; district tools work without it.

### What does it need to run?

Node.js 18 or later; it installs through npx as @betanyc/nyc-311-mcp.

### Is "closed" the same as fixed?

No. The site says closed only means an agency closed the request.

### Is NYC 311 free?

Yes. NYC 311 is open source, so you can use and self-host it for free.

### How do I add NYC 311 to Claude Code?

Run this command in your terminal: claude mcp add nyc-311-mcp --env NYC_311_API_KEY='<NYC_311_API_KEY>' --env SOCRATA_APP_TOKEN='<SOCRATA_APP_TOKEN>' -- npx -y @betanyc/nyc-311-mcp

### What are the best alternatives to NYC 311?

The closest alternatives to NYC 311 are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, Tapetide - Indian Stock Market MCP, World Monitor and CompanyData.

## Alternatives

- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [World Monitor](https://ai-powered.com/mcp/world-monitor): World Monitor is a freemium MCP server for analytics and data.
- [CompanyData](https://ai-powered.com/mcp/companydata): CompanyData is a paid MCP server for analytics and data.
- [NY LLC Publication (FileMyPublication)](https://ai-powered.com/mcp/ny-llc-publication-filemypublication): NY LLC Publication (FileMyPublication) is a free MCP server for legal and government.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [Quantivex Research](https://ai-powered.com/mcp/quantivex-research): Quantivex Research is a free MCP server for finance and payments.

---
Source: https://ai-powered.com/mcp/nyc-311
