Server data from the Official MCP Registry
NYC Council legislation: bills, hearings, votes and members, from a local index or live Legistar
About
NYC Council legislation: bills, hearings, votes and members, from a local index or live Legistar
Security Report
Valid MCP server (1 strong, 2 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Environment variable: LEGISTAR_TOKEN
Environment variable: LEGISTAR_DB_PATH
How to Install
Add this to your MCP configuration file:
{
"mcpServers": {
"nyc-council-mcp": {
"command": "npx",
"args": [
"-y",
"@betanyc/nyc-council-mcp@2.9.0"
],
"env": {
"LEGISTAR_TOKEN": "your-legistar-token-here",
"LEGISTAR_DB_PATH": "your-legistar-db-path-here"
}
}
}
}Some servers take additional arguments. See the repository for details.
Documentation
View on GitHubFrom the project's GitHub README.
@betanyc/nyc-council-mcp
An MCP (Model Context Protocol) server for NYC Council legislative data. Version 2 adds a hybrid mode: a local SQLite index for sub-second search and exploration, plus the live NYC Legistar API for authoritative real-time data.
What's changed: WHATS-CHANGED.md lists every change a reader would notice, newest first, including every correction and what to re-check. Your AI assistant can read it too, with the whats_changed tool.
What it does
Ask an AI assistant about New York City Council legislation and get answers grounded in the Council's own records: bills, resolutions and land use items, their full text and summaries, sponsors, hearings, votes, committee memberships and attachments.
The local index holds every matter in the jehiah/nyc_legislation archive: on 2026-11-11 that was 21,803 matters (13,059 Introductions, 6,198 Resolutions, 2,545 Land Use items), 17,532 meetings, 517,562 individual recorded votes and 254 people. The live tools read the Council's Legistar API directly.
What's new in 2.9.0
- "What changed?" and "Who built this?" Two new tools work in every mode, with no token or index.
whats_changedanswers from WHATS-CHANGED.md, the plain-language history of this server back to 1.0.0, including every correction and what to re-check.about_betanycsays who built the server, how to report a bug or ask for a feature, and which version of BetaNYC's shared code it runs. - BetaNYC's shared module 1.3.7.
about_dataanswers now give BetaNYC's contact for questions and error reports about the data (lab@beta.nyc), say who fixes an error in the data, the publisher or BetaNYC, and list any source the server cannot show. - With both data sources set up, the server now lists 28 tools.
What's new in 2.8.0
- Who holds a district. New tool
district_membersays who held Council District 1 to 51 on any date. It reads the City's list of every Council term since 1999 (NYC Open Datauvw5-9znb), which ships with the package. When the City's file is behind, the answer names the missing member. On 2026-11-12 that was Carl Wilson, District 3. See Known traps. - Committees, chairs and caucuses. New tools
get_member_rolesandcommittee_rostersay who chairs what and who sits where, today or on a past date, from Legistar's own membership records. Party is never inferred from a caucus. - Member facts curated by BetaNYC, labeled as such.
get_council_memberandget_member_rolesadd acuratedblock with Wikidata and Wikipedia links, party as every ballot line the member won on (NYC has fusion voting), and office social accounts. Each fact carries its source and check date, and the block says it is not an official record. Rules:data/README.md. - "Where does this data come from?" New tool
about_dataworks in every mode. It gives each source, its publisher, whether it is official or BetaNYC's curation, how current it is on this server, its terms, a credit line and where to report an error. The same facts are inDATA-SOURCES.jsonand a DCAT-US 3.0 catalog,data.json, with lab@beta.nyc as BetaNYC's contact. See Where the data comes from. - Search the full text. Local search now reads summaries and full text, not only titles. New tool
get_matterfinds one matter by file number or Local Law number, with its attachments. New live toolget_bill_attachmentslists a matter's files with download links. - Links for every matter type.
legistar_urlnow opens Resolutions, Land Use, M and T items, not only Introductions. Seelegistar_url. - Answers you can date and check. Every local answer names when the index was built and from which archive commit. With a token,
upcoming_eventschecks each meeting's status live. Vote times are New York local time, and voting records are ordered by vote date and name the member who voted. - Upgrading: the first
indexrun after upgrading rebuilds the index in full, once (about 25 seconds on the 2026-11-11 archive).
The full list is in CHANGELOG.md.
Quick start
The recommended setup, for Claude Code:
Register at user scope so the server is available from any project:
claude mcp add nyc-council-mcp \
--scope user \
npx -- -y @betanyc/nyc-council-mcp serve
Then add your environment variables to ~/.claude.json under the mcpServers entry:
{
"mcpServers": {
"nyc-council-mcp": {
"command": "npx",
"args": ["-y", "@betanyc/nyc-council-mcp", "serve"],
"env": {
"LEGISTAR_TOKEN": "your_token_here",
"LEGISTAR_DB_PATH": "/Users/you/legistar/legistar.db"
}
}
}
}
Set only LEGISTAR_TOKEN for live-only mode, or only LEGISTAR_DB_PATH for local-only mode.
Prerequisites
- Node.js 18 or later
- For live tools: a free Legistar API key — register here
- For local tools: the
jehiah/nyc_legislationarchive (~920 MB, one-time clone)
Installation
Recommended: hybrid mode (both data sources)
Step 1 — Get a Legistar API key
Register at council.nyc.gov/legislation/api. You'll receive a token by email.
Step 2 — Clone the legislation archive
git clone --depth 1 https://github.com/jehiah/nyc_legislation.git ~/legistar/nyc_legislation
This is about 920 MB and takes a few minutes. It only needs to be done once.
Step 3 — Build the local index
npx @betanyc/nyc-council-mcp index \
--archive ~/legistar/nyc_legislation \
--db ~/legistar/legistar.db \
--verbose
This takes roughly 25 seconds and produces a legistar.db file of about 1 GB. On the 2026-11-11 archive it indexed 21,803 matters, 17,532 events and 517,562 roll-call vote rows. It also loads the Council terms list that ships with the package, with no network call.
Step 4 — Configure your MCP client
Add both environment variables to your MCP config. See Configuration below.
Live-only mode (no local index)
If you only want the live Legistar API tools and don't need local search, just set LEGISTAR_TOKEN and skip the archive clone.
Local-only mode (no API key)
If you only want fast local search (no real-time data), set LEGISTAR_DB_PATH and skip the API key. Note: get_upcoming_hearings, get_bill (current status), and similar live tools will be unavailable. about_data, district_member and the other local tools work without a token.
Build from source
git clone https://github.com/BetaNYC/nyc-council-mcp.git
cd nyc-council-mcp
npm install && npm run build
LEGISTAR_TOKEN=your_token LEGISTAR_DB_PATH=./legistar.db node dist/index.js serve
Keeping your index fresh
The archive is updated most weekdays. Run these two commands to pull the latest data and update your index:
# Pull the latest archive files
cd ~/legistar/nyc_legislation && git pull
# Rebuild incrementally (only processes new/changed files — takes seconds after the first build)
npx @betanyc/nyc-council-mcp index \
--archive ~/legistar/nyc_legislation \
--db ~/legistar/legistar.db
You never need to wait for a BetaNYC-hosted snapshot. Incremental mode (the default) is fast enough to run manually whenever you want fresh data.
Automated daily updates (cron):
# Add to your crontab: daily at 6am
0 6 * * * cd ~/legistar/nyc_legislation && git pull && npx @betanyc/nyc-council-mcp index --archive ~/legistar/nyc_legislation --db ~/legistar/legistar.db
Force a full rebuild:
npx @betanyc/nyc-council-mcp index \
--archive ~/legistar/nyc_legislation \
--db ~/legistar/legistar.db \
--full
Note: The local index is only as current as your last index run — run the daily cron above and it stays about a day behind live Legistar; leave it for a month and it is a month stale. The upstream archive itself updates most weekdays. For current status and upcoming hearings, use the live API tools (
get_bill,get_upcoming_hearings).Every local answer ends with a source line: when the index was built and which
jehiah/nyc_legislationcommit it came from, e.g.Source: local index built 2026-11-12T11:30:07Z from jehiah/nyc_legislation@9e52935 (archive commit 2026-11-11T23:38:10Z).It is a second text item, after the JSON. With noLEGISTAR_TOKEN, the line also says the answer was not checked live, and that an empty answer means "not in this index", not "does not exist".Why upcoming meeting status is checked live: Legistar can change a meeting's status without updating its last-modified time. Event 22725 went from Final to Deferred with its timestamp still 2026-09-10, so the archive never fetched it again. On 2026-11-12, 10 of 658 meetings in 2026 differed this way, all Final → Deferred.
API key
A free API key is optional — it unlocks the live Legistar API tools, but the server also runs in local-only mode without one.
- Live tools (
get_billcurrent status,get_upcoming_hearings, confirmation queries) require a free Legistar API key. Register at council.nyc.gov/legislation/api — you'll receive a token by email — and set it as theLEGISTAR_TOKENenvironment variable. - Local fast-path tools (search, browse, voting history, aggregation) need no key — they read the local SQLite index at
LEGISTAR_DB_PATH.
You must set at least one of LEGISTAR_TOKEN or LEGISTAR_DB_PATH; set both for full hybrid mode. Example (live tools):
export LEGISTAR_TOKEN="your-legistar-token"
See Setup and Environment variables for full details.
Configuration
Environment variables
| Variable | Required for | Notes |
|---|---|---|
LEGISTAR_TOKEN | Live API tools | Register at council.nyc.gov/legislation/api |
LEGISTAR_DB_PATH | Local SQLite tools | Path to your built legistar.db |
| Do not commit tokens to version control. |
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"nyc-council": {
"command": "npx",
"args": ["-y", "@betanyc/nyc-council-mcp", "serve"],
"env": {
"LEGISTAR_TOKEN": "your_token_here",
"LEGISTAR_DB_PATH": "/Users/you/legistar/legistar.db"
}
}
}
}
Tools reference
Fast-path tools (local SQLite index)
These require LEGISTAR_DB_PATH and a built index (see Setup).
| Tool | Description |
|---|---|
search_legislation | Full-text search across all legislation: Introductions, Resolutions, Land Use and every other matter type. Searches titles, sponsors, summaries and the full text; a title hit ranks above a body hit. Rows carry version and local_law |
get_matter | One matter by file number (Int 1122-2024) or Local Law number (2025/153): summary, version, Local Law number, attachments with download links, legistar_url, and the full text on request (include_text) |
get_member_roles | A member's committees (chairs listed separately), caucuses, party conferences, borough delegations and task forces, from Legistar's own membership records, plus the member's council district and every term. Today by default; as_of for a past date; include_past for the full history with dates. No party is inferred from caucus or conference |
committee_roster | Who sits on a committee, chair first, on a date or across its history |
district_member | Who held a Council district (1–51) on a date, from the City's terms list (NYC Open Data uvw5-9znb, shipped as a dated snapshot). status is filled, vacant (nobody held it that day; the last member is previous, never current) or unknown (the City lists someone serving that day with no district, so the seat may be theirs). Overlapping terms are all shown |
search_bills | Alias for search_legislation (same tool, same results; kept so existing callers work) |
search_events | Full-text search across committee hearings |
list_committees | All committees with bill and event counts |
recent_bills | Bills introduced in the last N days |
upcoming_events | Scheduled events in the next N days. With LEGISTAR_TOKEN set, each meeting's agenda_status is checked live (status_checked_live; the index's value stays in agenda_status_index when they differ), and meetings the index doesn't have yet are listed in a note |
aggregate_bills | Count bills grouped by status, type, committee, or year |
vote_breakdown | Every member's vote on a bill (by type-prefixed file number), grouped by roll call — committee and full Council — each with a positions-only tally. Indexed from the archive's History[].Votes |
get_voting_record | All votes cast by a named council member, newest vote first. Each row has vote_date, vote_action and vote_body; intro_date is the bill's, not the vote's |
get_bill_history | A matter's action trail — hearings, referrals, committee/Council actions, outcomes — in chronological order, by file number. No token required |
co_sponsors | Members who most often co-sponsor with a given member |
get_bill_hearings | Events where a bill appeared on the agenda, with each event's date, body, and action |
get_event_bills | Items on one event's agenda, paged: { event_id, total, offset, limit, items }, 50 per page by default (max 500) |
Confirm-path tools (live Legistar API)
These require LEGISTAR_TOKEN.
| Tool | Description |
|---|---|
get_bill | Current status and record for a bill. A bare NNNN-YYYY number is ambiguous (it can be both an Int and a Res); an ambiguous match is rejected with an error naming every candidate, so re-call with the exact type-prefixed number |
get_bill_history | Local by default (served from the index, no token; takes a file number). In live-only mode this live variant answers instead — authoritative action trail by numeric matter id |
get_bill_attachments | Files attached to a matter (committee reports, resolution text, charts, transcripts), each with a direct download link. Takes the numeric matter id |
get_upcoming_hearings | Real-time upcoming committee hearings and Stated meetings, each with its agenda items (bills/matters) in EventItems. Short shape by default (detail: "summary": no null fields, titles cut at 300 characters, legistar_url per item); detail: "full" returns every Legistar field |
get_council_member | Current contact info and active status for a council member, plus a curated block (Wikidata/Wikipedia, party as every ballot line won on, office social accounts; BetaNYC's, not official) and, with a local index, district and terms. The name matches word by word, ignoring case, accents and middle initials ("Amanda Farias" finds "Amanda C. Farías"); get_voting_record and co_sponsors match names the same way. PersonWWW2 (the Legistar profile page) is checked: a known-bad upstream link is corrected from a small dated override list (PERSON_WWW2_OVERRIDES in src/legistar.ts, with the original kept in PersonWWW2_upstream), and a link shared by two people in one result gets a PersonWWW2_warning |
get_committee | Current membership count and details for a committee |
get_votes | Per-item vote breakdown by event item ID |
list_recent_legislation | Most recently introduced legislation (catches bills since last index) |
search_legislation_live | Live Legistar search (slower than local, always current). Multi-word queries match all words in any order; quote a "phrase" for adjacency. No relevance ranking upstream — results are ordered by intro date (order='date_asc' for oldest-first). |
About this server (every mode)
These need no token or index, and make no network call. They come from BetaNYC's shared module, the same in every BetaNYC MCP server.
| Tool | Description |
|---|---|
whats_changed | What changed in this server, newest first, from WHATS-CHANGED.md: new tools, new data, and every correction with what to re-check. since (YYYY-MM-DD), tag (Site, Data, MCP or Correction) and limit (1 to 50, default 10) narrow it. A change not released yet is left out |
about_betanyc | Who built this server (BetaNYC, a project of the Fund for the City of New York), links to BetaNYC, where to report a bug in this server or ask for a new feature, and the version of BetaNYC's shared module it runs. No inputs |
Where the data comes from (every mode)
| Tool | Description |
|---|---|
about_data | Ask the server where its data comes from. For each kind of data it gives the source and its publisher, whether it is an official record or BetaNYC's curation, how it was gathered and what BetaNYC changed, how current it is on this server (the index build time, the district snapshot's fetch time, the curated files' check dates), what it covers, terms of use and a credit line, where to check a figure, where to report an error, and which tools use it. topic narrows it to one kind of data (live, bills, votes, events, committees, districts, party, wikidata, social) or to the data behind one tool (for example get_council_member). It gives BetaNYC's contact for questions and error reports about the data, lab@beta.nyc. For who built the server, the answer points to about_betanyc. With no LEGISTAR_TOKEN, the live source says it is not available on this server. Needs no token or index. The server's MCP instructions tell the AI app to call it whenever someone asks about sources, freshness or accuracy, and to say when figures are not an official record. Answers come from DATA-SOURCES.json, read by BetaNYC's shared module. |
Tool details
search_legislation / search_bills
Full-text search across the local index, which covers Introductions,
Resolutions, and Land Use Applications. Multi-word queries match matters
containing all the words in any order; quote a "phrase" to require adjacency.
Upgrading from ≤ 2.1.1: Resolutions and Land Use matters were previously absent from the index. Re-run
npx @betanyc/nyc-council-mcp index …after updating to pick them up.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | yes | — | Search terms |
limit | number | no | 25 | Max results (max 100) |
agency | string | no | — | Agency key or name for role-context snippets (e.g. DEP, NYPD) |
status | string | no | — | Filter by status (e.g. Enacted, Laid Over) |
committee | string | no | — | Filter by committee name |
search_bills("open data")
search_bills("bicycle lane", agency="DOT", status="Enacted")
search_bills("tenant protection", committee="Housing")
aggregate_bills
Count bills grouped by a dimension.
| Parameter | Type | Required | Options |
|---|---|---|---|
group_by | string | yes | status, type, committee, year |
aggregate_bills(group_by="status")
aggregate_bills(group_by="year")
Roll calls are indexed locally (#30). Each matter's
History[].Votesis indexed into avotestable, sovote_breakdown,get_voting_record, andget_bill_historyanswer from the corpus with no token. A member's entry is a position (Affirmative / Negative / Abstain) or a non-position reason for not casting one (Absent, Excused, Medical …); both are stored, but a tally counts positions only — an Absent member is never scored as a vote. If thevotestable is empty the tools still raise a named error rather than return[](which reads as "cast no votes"); that means the corpus predates roll-call indexing and needs anyc-council-mcp indexrebuild.get_votesremains for live per-item positions.
vote_breakdown
Every member's vote on a matter, grouped by roll call (committee and full Council
appear separately), each with a positions-only tally. Res 0540-2026 returns its
Council roll call (45–6, 51 recorded) and its Committee on Finance roll call (14–1,
17 recorded — the tally is 14–1, not 17).
| Parameter | Type | Required | Description |
|---|---|---|---|
file_number | string | yes | Type-prefixed file number, e.g. Res 0540-2026. A bare NNNN-YYYY that matches both an Int and a Res is rejected, naming each |
get_bill_history
A matter's action trail in chronological order — introduced, referred, heard, amended,
approved, enacted — one row per action, with the acting body and date. Served from the
local matter_history table, so it needs no token. Each action also carries the
event_item_id of the meeting item it happened at, which is the id get_votes takes if
you want to confirm a roll call against the live API.
| Parameter | Type | Required | Description |
|---|---|---|---|
file_number | string | yes | Type-prefixed file number, e.g. Int 1122-2024 |
get_voting_record
All votes cast by a council member.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
member_name | string | yes | — | Full or partial name |
limit | number | no | 50 | Max results |
co_sponsors
Members who most frequently co-sponsor bills with a given member.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
member_name | string | yes | — | Full or partial name |
limit | number | no | 20 | Top N co-sponsors |
Agency snippets
When you pass agency to search_bills, results include a role-context snippet showing HOW the agency appears in the bill — whether it is directed, consulted, or reporting. This helps distinguish bills that merely mention an agency from those that grant or restrict its authority.
Supported agency keys: DEP, DOT, NYPD, FDNY, DOB, HPD, HRA, DSS, ACS, DOHMH, DHS, DCAS, DSNY, DPR, DCP, FINANCE, LAW, MAYOR, COMPTROLLER, MTA, EDC, SBS, DCWP, DYCD, DFTA, DOE, CUNY, and more.
You can also pass a full name: agency="department of transportation" or agency="sanitation".
Common workflows
Explore a topic, then confirm
1. search_bills("e-bike") → sub-second results from local index
2. get_bill("Int 0042-2024") → authoritative current status from live API
3. get_bill_history("Int 0042-2024") → full action trail from the local index (no token)
4. vote_breakdown("Int 0042-2024") → how each member voted, per roll call, from the local index
Analyze a council member's record
1. get_voting_record("Nurse") → all votes cast
2. co_sponsors("Nurse") → frequent co-sponsors
3. search_bills("bicycle", committee="Transportation") → bills in their area
Who represents a district, and what do they chair?
1. district_member(district=3) → who held the seat today (or as_of a past date)
2. get_member_roles("Brewer") → committees, chairs, caucuses, district and terms
3. get_council_member("Gale Brewer") → live contact info, plus the curated block
4. about_data(topic="party") → where the party lines came from, and that they are BetaNYC's curation
Track upcoming hearings
1. upcoming_events(days=14) → from local index (as fresh as your last index run)
2. get_upcoming_hearings() → from live API (real-time)
get_upcoming_hearings populates each event's EventItems array with the agenda
items (the bills/matters on that hearing's agenda), fetched per event from the
Legistar /events/{EventId}/eventitems endpoint. The /events list endpoint
itself always returns EventItems empty and ignores $expand, so the follow-up
call is required. Pass include_agenda=false to skip it and return the hearing
schedule faster with EventItems empty.
How it works
Two-speed design
| Path | Speed | Data | Use for |
|---|---|---|---|
| Local index (SQLite) | < 1 second | As fresh as your last index run | Search, browse, voting history, aggregation |
| Live API (Legistar) | 1–5 seconds | Real-time | Current status, upcoming hearings, confirmation |
Use both together for the best experience. Search locally to explore; confirm with the live API when accuracy matters.
Index CLI reference
nyc-council-mcp index [options]
Options:
--archive <path> Path to jehiah/nyc_legislation clone (required)
--db <path> SQLite output path (default: $LEGISTAR_DB_PATH or ./legistar.db)
--full Force a full rebuild (default: incremental)
--verbose Print progress to stderr
--help Show help
Incremental mode upgrades itself to a full rebuild when it has to. Even without
--full, the indexer rebuilds from scratch if either has changed since your last run:
- the schema version — the corpus was built by an older release whose tables differ, or
- the set of indexed sources — the indexer now walks matter trees it did not before.
This matters because an incremental run skips files by modification time, so widening
coverage would otherwise leave older files permanently unindexed. When a trigger fires,
--verbose names it and the run drops and recreates the data tables before indexing.
Upgrading to 2.8.0 (schema version 6) fires the schema trigger once, so your first index
after upgrading takes a full rebuild (about 25 seconds) and picks up full text, Local Law
numbers, attachments, membership records and Council terms. Until then, an older index keeps
working: search returns null version and local_law, and the new tools say to re-index.
Every run, full or incremental, also reloads the Council terms snapshot that ships in the
package (data/council-member-terms.json). It needs no network.
An archive with no matching files is an error, not an empty index. If --archive
points at a directory where none of people/*.json, introduction/**/*.json,
resolution/**/*.json, land_use/**/*.json or events/**/*.json match, index exits
non-zero and leaves any existing database untouched. A source directory that exists but
matches nothing is reported on stderr. The build uses portable paths (including archive
paths with spaces, parentheses or brackets) and is tested in CI on Windows as well as Linux.
Notes and limitations
legistar_url — the human-openable link
Bill/matter records include a legistar_url field: a link a person can click to
open the matter on Legistar. It works for every matter type (Int, Res, LU, M,
T, …) and looks like:
https://legistar.council.nyc.gov/gateway.aspx?M=L&ID={MatterId}
Why this shape, so nobody re-attempts the obvious-looking fix:
- NYC runs two Legistar backends with different ids. The WebAPI this server
reads exposes
MatterId/MatterGuid; the publicLegislationDetail.aspxpage keys on a separate ID/GUID that is not in the API record. SoLegislationDetail.aspx?ID={MatterId}returns "Invalid parameters!". gateway.aspx?M=L&ID={MatterId}takes the API id and redirects to the rightLegislationDetail.aspxpage. Checked 2026-11-12 on Res 0551, 0595, 0652 and 0695-2026, T2026-2764 and an Introduction: each landed on its own page. An id that does not exist shows "This record is currently unavailable."- Caveat:
gateway.aspxis not in Granicus's published API docs. It is how the Legistar site links to its own records — observed behavior, not a documented contract.LEGISTAR_LIVE_URL_TEST=1 npm testre-checks the fixtures live. - A row with no matter id (a procedural agenda line) gets
null. - Through 2.7.1 the link came from intro.nyc, which keys on the
bare number and assumes an Introduction, so every other type got
null(#45).
Known traps
- Vote and history times are New York local time (
2026-10-22T13:30:00). The archive marks them as UTC by mistake; the indexer drops that marker. - A partial name can match several members.
get_voting_record("Williams")returns votes by Jumaane D. Williams and Nantasha M. Williams; each row'sperson_namesays whose vote it is. - One vote row per roll call.
get_voting_recordreturns a row for each roll call a member voted in, so an item voted on in committee and then by the full Council appears twice.vote_bodyandvote_datetell them apart; dedupe byfile_numberto count distinct matters. - The archive can miss a meeting status change. Legistar sometimes changes a meeting's status (e.g. to Deferred) without updating its last-modified time, so the archive keeps the old one. With
LEGISTAR_TOKENset,upcoming_eventschecks status live; without it, useget_upcoming_hearingsbefore relying on a date. get_event_billsis paged. A stated meeting can have 170+ agenda items; readtotaland raiseoffsetto get them all.- A caucus or conference is not a party.
get_member_rolesreports Legistar's caucus and party-conference memberships as memberships only. Party appears only in thecuratedblock, which lists every ballot line the member won on, copied from Board of Elections certified results. curatedis BetaNYC's work, not an official record. The Wikidata/Wikipedia link, party lines and office social accounts in each member'scuratedblock were checked by hand on the date shown, against the source given. A blank staysnull. Seedata/README.md.- Districts come from a snapshot.
district_memberand thedistrictfield read the City'suvw5-9znbfile as shipped, with its fetch date in every answer. The City updates that file late: on 2026-11-12 it had no term for Carl Wilson, a Council Member since 2026-05-13, so District 3 showed vacant. A vacant answer names such people underunlisted_council_members; check council.nyc.gov before saying a seat is empty. District lines are redrawn, so a past member's district number may not match today's map. search_billsis an alias ofsearch_legislation. Both return every matter type, not only bills.- Local answers end with a source line saying when the index was built and from which archive commit. An empty local answer means "not in this index", not "does not exist".
Testing and CI
npm test # builds, then runs every test offline
LEGISTAR_LIVE_URL_TEST=1 npm test # with LEGISTAR_TOKEN set: adds the live checks (read-only GETs)
Tests use Node's built-in runner (node --test test/*.test.mjs) and never need the network unless LEGISTAR_LIVE_URL_TEST is set. CI runs them on every pull request to main, on Ubuntu (Node 20 and 22) and Windows (Node 22), and a version guard fails any PR that changes shipped code without a version bump.
CI fails if DATA-SOURCES.json is invalid or leaves a tool without a source (a test checks this too), or if data.json, the DCAT-US 3.0 catalog made from it, is out of date or invalid. These checks follow BetaNYC's about-data standard. Rebuild it with python3 scripts/whats_changed.py about-data catalog DATA-SOURCES.json. CI also checks WHATS-CHANGED.md on every pull request: its format, that a published entry is only ever added to, and that a version bump comes with an entry naming the new version. src/betanyc-tools.ts, scripts/whats_changed.py, scripts/tests/catalog_validate.py and scripts/mcp_shared/ are copies of BetaNYC's shared files: do not edit them here.
The council terms snapshot (data/council-member-terms.json) is refreshed by node scripts/refresh-member-terms.mjs. A monthly workflow runs it and opens a PR when the City's rows change. The snapshot ships in the package, so a refresh needs a version bump like code does.
Contributing
Issues and pull requests welcome at github.com/BetaNYC/nyc-council-mcp.
Before working on the code, read CONTEXT.md — the project's glossary. It
pins down the distinctions this domain punishes you for blurring: a matter versus a
bill versus a file number (which is not unique without its type prefix), an event
versus an event item (different id spaces), and a position versus a non-position in a
roll call (both live in the same field, so a tally must filter rather than count rows).
Releases
Publishing is automated. To cut a release:
- Bump
versioninpackage.jsonin a PR, with a matching CHANGELOG.md entry and a WHATS-CHANGED.md entry tagged MCP. The What's changed entry is## Unreleased: Titleuntil the release. - Merge the PR.
- On the release day, in one commit: change
## Unreleased: Titleto## YYYY-MM-DD: Title(same title), give the CHANGELOG heading the same date, and point the entry's MCP version link at the dated CHANGELOG heading. - Push the matching tag:
git tag v<version> && git push origin v<version>. - The release workflow runs tests, verifies the tag matches
package.jsonandserver.json, runs the two release checks (anUnreleased:entry left in WHATS-CHANGED.md, or an error or placeholder contact in DATA-SOURCES.json, stops it), publishes to npm with provenance, and creates a GitHub Release. - When it succeeds, publish-mcp.yml lists that version in the official MCP Registry as
io.github.BetaNYC/nyc-council-mcp. Bumpversioninserver.json(both places) together withpackage.json.
Prerequisite: the NPM_TOKEN org secret (an npm automation token with publish rights on @betanyc) must be configured. Do not run npm publish by hand.
Data sources
- Live tools: NYC Council Legistar API, provided by Granicus
- Local index: jehiah/nyc_legislation archive — has been mirroring Legistar since 2018, updated most weekdays
- Curated member facts: Wikidata, Wikipedia, NYC Board of Elections certified results (party lines), council.nyc.gov and the Council's Bluesky starter pack (office accounts). Rules in
data/README.md - Council districts and terms: NYC Open Data City Council Members (1999 to Present) (
uvw5-9znb), shipped as a dated snapshot and used as published
The full list, source by source, is DATA-SOURCES.json (also as a DCAT-US 3.0 catalog, data.json), and the about_data tool answers from it.
Acknowledgments
This project builds on the foundational work of @jehiah, whose nyc_legislation project has been mirroring NYC Council legislative data since 2018 and powers intro.nyc.
The local SQLite index and agency snippet approach are adapted from WillHsiaoNYC/legistar-mcp, which introduced the two-speed architecture and role-context snippet design that v2 implements in TypeScript.
Thank you to Nathan Storey for including this project in the Civic AI Tools Directory.
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 throughout the year — 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.
Freedom isn't free. Support BetaNYC.
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-charter-laws-rules: trace a bill through to the Charter, Administrative Code, and Rules text it amends.
- nyc-budget-mcp: connect Council members and legislation to the discretionary funding (Schedule C) they direct.
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.
License
MIT License — Copyright (c) 2026 BetaNYC, a project of the Fund for the City of New York
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
