NYC 311
Answers about reporting problems to NYC 311 and your district's reports, from City data
- Pricing
- Open source
- Platforms
- CLI, macOS, Windows
- Runs
- Locally
- Version
- 1.3.0
- Listing updated
- 3 days ago
About NYC 311
NYC 311 is an open-source MCP server for legal and government. It runs locally on your machine and is started by your AI client.
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.
Install
Run in a 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-mcpAdd to claude_desktop_config.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>"
}
}
}
}Add to ~/.cursor/mcp.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>"
}
}
}
}Add to .vscode/mcp.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>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.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>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"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>"
}
}
}
}Configuration
NYC_311_API_KEYFree NYC 311 Public API key for the calendar, status, request lookup and reporting tools. The district tools work without itSOCRATA_APP_TOKENOptional NYC Open Data app token, used by the call center reportNYC_311_MCP_CACHE_DIRFolder for the data cache (about 85 MB of public City data). Defaults to the system cache folder
Tools this server provides (5)
Taken from the project documentation; the running server may differ.
- 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.
What it does
- 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
Pricing
Open source
Free and open source
Prices change. Check betanyc.github.io before you buy.
NYC 311 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 to NYC 311

Agent-Native Analytics
MCP serverOpen-source analytics app where an AI agent builds charts and dashboards from your data
- Remote
- Open source
- 7.7K GitHub stars
- Analytics and data

Google Ads + Meta Ads + SEO/GEO MCP
MCP serverHosted MCP connector for managing Google Ads, Meta Ads, GA4 and Search Console from chat
- 8 tools
- Remote
- Freemium
- 8.1K GitHub stars
- Marketing and SEO

Tapetide - Indian Stock Market MCP
MCP serverIndian NSE and BSE stock market data for AI assistants through 48 MCP tools
- 17 tools
- Remote
- Freemium
- 150 GitHub stars
- Finance and payments

World Monitor
MCP serverLive geopolitical intelligence dashboard with an API and MCP server for agents
- Remote
- Freemium
- Analytics and data

CompanyData
MCP serverSearch and enrich company records from official registers via the CompanyData API
- 3 tools
- Remote
- Paid
- 3 GitHub stars
- Analytics and data

NY LLC Publication (FileMyPublication)
MCP serverNew York LLC publication rules, deadline, county prices, clerks and notice text
- 8 tools
- Remote
- Free
- Legal and government