Skip to content
MCP server

NYC 311

Answers about reporting problems to NYC 311 and your district's reports, from City data

Runs locallyStatus and history
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-mcp

Add 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 it
  • SOCRATA_APP_TOKENOptional NYC Open Data app token, used by the call center report
  • NYC_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

  1. Open-source analytics app where an AI agent builds charts and dashboards from your data

    • Remote
    • Open source
    • 7.7K GitHub stars
    • Analytics and data
  2. Hosted 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
  3. Indian NSE and BSE stock market data for AI assistants through 48 MCP tools

    • 17 tools
    • Remote
    • Freemium
    • 150 GitHub stars
    • Finance and payments
  4. World Monitor

    MCP server

    Live geopolitical intelligence dashboard with an API and MCP server for agents

    • Remote
    • Freemium
    • Analytics and data
  5. CompanyData

    MCP server

    Search and enrich company records from official registers via the CompanyData API

    • 3 tools
    • Remote
    • Paid
    • 3 GitHub stars
    • Analytics and data
  6. New York LLC publication rules, deadline, county prices, clerks and notice text

    • 8 tools
    • Remote
    • Free
    • Legal and government