nyc-checkbook-mcp

Bringing New York City's checkbook to AI assistants everywhere.

An MCP (Model Context Protocol) server for NYC Checkbook data — spending, contracts, budget, payroll, and revenue — powered by the Checkbook NYC public API.

Checkbook NYC is the NYC Comptroller's financial transparency platform. It tracks $129B+ in annual city spending across 52,000+ vendors and 188,000+ contracts.

Vibe coded with Claude by BetaNYC.

Contents

• Getting started

• What it does

• Tools reference

• Example queries

• Common agency codes

• Installation

• Claude Desktop configuration

• API notes and limits

• Getting help and the upstream project

• Contributing

• Development

• About BetaNYC

• Related BetaNYC MCP servers

• Releases

• Acknowledgments

• License

Related MCP server: mcp-treasury

Getting started

To use this server you will need:

• Node 18 or later

• An MCP client, such as Claude Desktop or Claude Code

No API key is required. Checkbook NYC is a public API, so this server works out of the box — no signup, no token, no environment variables to set.

Note that the API is rate-limited to one request per second. This server enforces that internally, so you do not need to manage it yourself. See API notes and limits.

What it does

Exposes 9 tools over MCP:

Finding a vendor by name? The contracts API filters vendors only by vendor_code (there is no name lookup). Use search_spending(payee_name="…") to find checks paid to a named vendor. Note that many NYC contracts are held by resellers, so a software/product name may not match the contract's own vendor.

Tools reference

smart_search is disabled by default and is intentionally not documented as a usable tool here. The checkbooknyc.com /smart_search path is not a supported Checkbook NYC API endpoint — it is a WAF-fronted (Incapsula), JavaScript-rendered web page, confirmed with the NYC Comptroller's office. This server does not call it by default; the tool stays registered but returns opt-in guidance unless CHECKBOOK_ENABLE_SMART_SEARCH=1 is set (and even then it is almost always WAF-blocked server-side). For vendor-name lookups use search_spending(payee_name="…").

search_contracts

Search registered or pending NYC contracts with structured filters.

Known API limitation: registered revenue searches with fiscal_year return no rows. Checkbook NYC reports a match count but sends no records, whatever columns are requested (live, 2026-10-16). The tool refuses that combination with an error and guidance, without sending a request. Search without fiscal_year and narrow by date range instead.

Registered expense and all responses include documented WBE/EBE flags (prime_woman_owned_business, prime_emerging_business) and lineage/registration columns (mocs_registered, contract_class, parent_contract_id, prime_contract_version) in addition to the core fields.

Record field names depend on status and category. The API resolves a different domain for each, and records are returned with the API's own field names, not normalized:

search_contracts(agency_code="858", fiscal_year="2024")
search_contracts(vendor_code="V0000012345", status="registered")
search_contracts(amount_min=100000, amount_max=500000, mwbe_category="3")
search_contracts(agency_code="858", fiscal_year="2024", include_sub_vendors=true)

Finding contracts by vendor NAME: the contracts API filters vendors only by vendor_code, not by name (there is no name→code lookup in the API). To search by name, use search_spending(payee_name="…") for checks paid to a vendor. Many contracts are held by resellers, so a product/software name may not match the contract's own vendor.

get_contract

Look up a single contract by ID.

get_contract("CT185820201424467")
get_contract("DO185820252009241")

search_spending

Search NYC spending records (checks issued to vendors).

*Either fiscal_year or issue_date_from is required (enforced).

search_spending(agency_code="858", fiscal_year="2024")
search_spending(payee_name="SHI International", fiscal_year="2025")

search_budget

Search NYC budget allocations.

search_payroll

Search NYC payroll records. Requires fiscal_year or calendar_year.

The Checkbook NYC API does not expose employee names — payroll records are keyed by agency, title, pay frequency, and pay date. There is no employee-name search.

*Either fiscal_year or calendar_year is required (enforced).

search_revenue

Search NYC revenue data.

get_agency_spending

All spending for a specific agency in a fiscal year.

get_agency_spending("858", "2025")   // OTI/DoITT
get_agency_spending("040", "2025")   // NYPD

search_nycedc_contracts

Search NYCEDC / Other Government Entities (OGE) contracts (Checkbook domain Contracts_OGE), which are separate from citywide contracts. Registered expense contracts only.

Results carry apt_pin only when you do not filter by fiscal_year. The API lists that response column as valid without fiscal_year and rejected it on a fiscal_year search (#40), so it is requested only then.

search_nycha_contracts

Search NYCHA (New York City Housing Authority) contracts (Checkbook domain Contracts_NYCHA), reported at release / line-item granularity (funding source, program/project, responsibility center).

Results carry a year field only when you filter by fiscal_year. The API lists the year response column as valid with fiscal_year and rejected it on a search without (#40), so it is requested only then. Without fiscal_year, results carry no year or fiscal-year field. When the year matters, filter by fiscal_year, one call per year. Each record still has its own start_date, end_date, and approved_date.

Example queries

Natural-language questions this MCP can answer today, by persona:

• Watchdog/journalist: "How much did the city actually pay a given vendor in FY2024, and through which agencies?" — search_spending filters payment records by payee name, agency, fiscal year, date range, and amount.

• Accountability researcher: "Which registered expense contracts over $500,000 did the Department of Transportation hold in FY2025?" — search_contracts filters by agency, fiscal year, amount range, status, industry, and M/WBE category (use get_contract for full detail on one contract by ID).

• Budget analyst: "What was the NYPD's adopted budget for FY2026, broken down by budget code?" — search_budget returns budget lines by agency, department, budget code, and fiscal year (get_agency_spending gives the companion "what did they actually spend" view).

• Labor/compensation reporter: "What did FDNY paramedics earn in FY2026, and which pay frequencies show the most supplemental pay?" — search_payroll filters by agency, job title, pay frequency, pay date, and amount range.

• Fiscal-policy researcher: "How much revenue did the Department of Finance collect in FY2025, grouped by revenue category?" — search_revenue filters by agency, revenue category/class/source, fund class, and fiscal year.

Common agency codes

Installation

npx (recommended — no install required)

npx @betanyc/nyc-checkbook-mcp

From 1.6.4, each release is also published to the official MCP Registry as io.github.BetaNYC/nyc-checkbook-mcp.

Global install

npm install -g @betanyc/nyc-checkbook-mcp
nyc-checkbook-mcp

No API key required — Checkbook NYC is a public API.

Claude Desktop configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "nyc-checkbook": {
      "command": "npx",
      "args": ["-y", "@betanyc/nyc-checkbook-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "nyc-checkbook": {
      "command": "nyc-checkbook-mcp"
    }
  }
}

API notes and limits

Limits

The NYC Comptroller's office publishes these limits for the Checkbook NYC API. Both were confirmed directly with their team on 2026-07-28.

Exceeding the rate limit has consequences beyond a throttle. The API sits behind an Imperva edge that will place a client into a blocked state that persists well past the burst that caused it, and presents as an HTTP 403 on every subsequent request, including from an ordinary browser on the same network. If you fork this server or write your own client, pace your requests.

This server also declines to follow HTTP redirects. A redirect chain is followed inside a single fetch() call, where rate pacing cannot reach it, so one logical API call can arrive at the origin as dozens of requests.

Other notes

• Endpoint: POST https://www.checkbooknyc.com/api

• Format: XML (handled internally — tools accept and return JSON)

• Authentication: none. Requests identify themselves only by User-Agent.

• Coverage: Citywide agencies + NYCEDC and NYCHA as other government entities (OGE)

• Fiscal year: NYC fiscal year runs July 1 – June 30 (FY2025 = July 2024 – June 2025)

• smart_search is disabled by default: the /smart_search web path is not a supported API endpoint (WAF-fronted, JS-rendered), so the server does not call it unless CHECKBOOK_ENABLE_SMART_SEARCH=1 is set. Use the structured XML-API tools; see the note under Tools reference.

Getting help and the upstream project

Questions about this MCP server belong in our issue tracker.

Questions about Checkbook NYC itself, the data, the API, or the platform, belong upstream with the Comptroller's office. Checkbook NYC is open source, and the office runs a public technical discussion forum:

You can post to the forum by web or by email, and you do not need to be subscribed to post.

Please take questions about data accuracy, field definitions, coverage gaps, and API behavior to the forum rather than to our tracker. They are better answered by the people who maintain the platform, and asking in the open helps everyone else building against the same API.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to report an issue, propose a change, and what we ask of code contributions.

One request specific to this project: do not add code that queries undocumented endpoints or that would exceed the published rate limit. This server talks to a public service run by a city agency on a fixed budget, and our access depends on being a well-behaved client.

Development

git clone https://github.com/BetaNYC/nyc-checkbook-mcp.git
cd nyc-checkbook-mcp
npm install
npm run build

Testing

Tests use the Node built-in test runner and live in test/. They run against recorded fixtures in test/fixtures/ rather than the live API, so the suite needs no network access and cannot trip the rate limit.

Three areas carry tests worth knowing about before you change them:

• test/pace.test.mjs guards the rate limiter, including the case where several callers are in flight at once. If you change how requests are dispatched, these are the tests that catch a regression into bursting.

• test/strict-schema.test.mjs asserts that unknown tool parameters are rejected rather than silently dropped.

• test/check-default-columns.test.mjs tests the default-column checker against a recorded probe snapshot. It proves the checker works, not that the columns are valid today. Only a fresh probe run can show that (see Releases).

Source layout

• src/index.ts starts the server and registers tools

• src/checkbook.ts holds the API client, request pacing, XML construction, and response parsing

• src/tools.ts holds tool definitions, schemas, and criteria mapping

About BetaNYC

This project is built and maintained by BetaNYC, New York's civic technology and open-data community. We work to improve lives in New York through civic design, technology, data, and public-interest technology.

Come do civic tech with us. We run public events, meetups, and hands-on data classes — including NYC School of Data and CityCamp NYC, and we host frequent civic-tech gatherings. See what's coming up on our events calendar.

Sustain this work. These MCP servers are free and open source. To help keep this work going and find BetaNYC's tools, please consider donating and becoming a Beta Builder.

Building on this? Tell us!

If you build something with this project, we'd love to hear about it. We can help other New Yorkers find it. BetaNYC publishes a weekly newsletter, This Week in NYC's Civic Technology and Open Data.

• Subscribe to the newsletter to keep up with NYC civic tech, open data, and public-interest technology.

• Built something, or found a story worth sharing? Submit a link for the newsletter and we'll consider it for an upcoming issue.

Related BetaNYC MCP servers

BetaNYC maintains a suite of open-source MCP servers for NYC and NYS civic data. See the full directory, with install details for each, at beta.nyc/ai-tools.

This server pairs directly with:

• nyc-budget-mcp: trace agency spending and contracts back to the Council discretionary awards (Schedule C) that funded them.

• nyc-record-mcp: connect a registered contract to the procurement solicitation and award notice that preceded it.

Releases

Before tagging, check the default response columns against the live API. A single rejected response column fails the whole request, so it can disable a tool outright, and default columns have been wrong four times (#16, v1.6.1, #40, #42). With no MCP client running:

bash scripts/probe-api-spec.sh   # 43 paced requests, ~65s; run it once, alone
npm run check:columns            # must exit 0

Then make one paced live call per contract shape and confirm each returns at least one row: search_contracts for registered expense, registered revenue (without fiscal_year; with it, the API is known to return no rows, see below), registered all, and pending; get_contract for one revenue contract; plus search_nycha_contracts and search_nycedc_contracts with and without fiscal_year. Space the calls out, and run them alone. The checker cannot catch this: a column the API accepts can still make it return no rows (contract_class on revenue contracts, #42). The server now reports that case as an error ("matched N records but returned none"), not as an empty page, so an isError here is the signal to bisect the column list. If even contract_id alone returns no rows, the defect is upstream, not in a column: registered revenue with fiscal_year is one such case (live, 2026-10-16; 399 matched, no rows for any column set).

If the probe aborts with a 403, that is a rate-limit block: stop, and do not re-run it to check. If the checker reports UNVERIFIED, follow scripts/README.md. probe-results.txt is git-ignored.

Publishing is automated. Pushing a tag of the form v<version> (matching package.json) runs .github/workflows/release.yml, which tests, publishes to npm with provenance, and creates a GitHub Release with generated notes. Requires the NPM_TOKEN repository secret. Changes are tracked in CHANGELOG.md.

Acknowledgments

Thank you to the NYC Office of the Comptroller for building and maintaining Checkbook NYC as a public resource, and for open-sourcing the platform at github.com/NYCComptroller/Checkbook. Financial transparency infrastructure like this makes civic research and accountability work possible.

Support our work

Freedom isn't free. Support BetaNYC.

License

MIT © BetaNYC