Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@us-open-stats-mcp What's the current unemployment rate in California?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server exposing normalized Census, BLS, FRED, and HUD tools. Returns small typed JSON snapshots suitable for editors and CLI clients.
Live infographics (embeddable): us-open-stats-mcp.pages.dev
uv sync --extra dev
./scripts/smoke.shRelated MCP server: Slacking-Biz
uv run us-open-data-mcp serve
uv run python scripts/build_demo_site.py
uv run pytest -qDemo UI: cd site && python3 -m http.server 8789
Premium Vite + React + ECharts reports live in web/. Build emits into site/ (Fraunces + Archivo, donut/hbar/lollipop/scatter/line charts, filterable listings, /embed/:id iframes).
cd web && npm install && npm run build
# or
uv run python scripts/build_demo_site.py{
"mcpServers": {
"us-open-stats": {
"command": "uv",
"args": ["run", "--directory", "/path/to/us-open-stats-mcp", "us-open-data-mcp", "serve"]
}
}
}Tool | Agency |
| Census ACS |
| HUD |
| BLS |
| BLS |
| FRED |
Default responses use recorded fixtures so CI stays offline. Live API keys can be added later without changing tool names.
MIT — see LICENSE.
Return ACS population estimate for a CBSA.
| Name | Required | Description | Default |
|---|---|---|---|
| cbsa | Yes | ||
| year | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden but discloses almost nothing: no indication of data vintage, ACS survey year semantics, rate limits, or that this is a non-mutating lookup. 'ACS' hints at the data source but no operational behavior is described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, which is appropriate sizing for a simple lookup. It is efficient, though the brevity tips into under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, but with 0% parameter coverage and no annotations the definition leaves the CBSA format and the year parameter undocumented. For a two-parameter tool this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and does not. It never explains the expected CBSA identifier format (e.g., 5-digit FIPS code) and completely ignores the 'year' parameter, which defaults to 2023.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Return) and resource (ACS population estimate) scoped to a CBSA, which is clearly distinct from sibling tools covering unemployment rate, CPI, and FMR. It lacks any explicit contrast with siblings, but the resource itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, no prerequisites, and names no alternatives. An agent must infer usage entirely from the name and the parameter list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a BLS CPI series point.
| Name | Required | Description | Default |
|---|---|---|---|
| series_id | No | CUSR0000SA0 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It does not state whether an API key is needed, whether the call is rate-limited, what units or seasonal adjustment apply, or the freshness/frequency of the data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded and wastes no words, but at this length it is under-specified rather than genuinely concise. It leaves the reader with no more routing or parameter information than the tool name alone.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, which lightens the burden. Still, for a data-retrieval tool with an undocumented, defaulted series_id and a close sibling in get_fred_series, the description omits routing and parameter context the agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the single parameter series_id has no description, so the description must compensate — it does not. It never explains the meaning of series_id, valid BLS series formats, or what the default value CUSR0000SA0 represents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb and resource ("Return a BLS CPI series point") and names the data source (BLS), so the agent knows it fetches CPI data. However, it does not distinguish this from siblings that overlap heavily, notably get_fred_series, which can also serve economic time series. "Point" is also ambiguous about whether one observation or a series is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance is given. It never mentions when to prefer this over get_fred_series (which also covers CPI), nor whether series_id should be customized or left at default. The agent must infer routing purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a FRED series observation from fixtures (live key optional later).
| Name | Required | Description | Default |
|---|---|---|---|
| series_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It does reveal that data comes from fixtures and that a live key may be optional later, but it does not clarify read-only behavior, error handling, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. The parenthetical about a future live key is slightly tangential but very brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with an output schema, the description covers the core purpose adequately. However, missing parameter semantics and lack of sibling differentiation leave meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter series_id has 0% schema description coverage. The description implies it is a FRED series identifier, but adds no format, examples, or constraints to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Return) and resource (FRED series observation), with source details (fixtures). It is clear but does not distinguish itself from sibling data-retrieval tools such as get_cpi or get_unemployment_rate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, alternatives, or prerequisites are provided. The parenthetical about a live key being optional later does not help an agent decide when to call this tool instead of its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return HUD Fair Market Rent for an entity id.
| Name | Required | Description | Default |
|---|---|---|---|
| bedrooms | No | ||
| entity_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Return' implies a read, but the description says nothing about whether entity_id must reference a geography or property, what the bedroom parameter does, or any failure modes for invalid ids. For a lookup tool with zero annotation coverage this is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler, so sizing is efficient. It is arguably too terse for a tool whose key parameter is undefined, but it wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required, which lightens the burden. Still, with 0% schema coverage and no annotations, the definition leaves entity_id and bedrooms unexplained, so an agent lacks enough to call it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and largely does not. It references entity_id only obliquely and never mentions the bedrooms parameter (default 2), whose meaning and allowed range are entirely undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Return HUD Fair Market Rent'), which is far more precise than the sibling tools' more generic data lookups. However, it offers no differentiation from siblings like get_cbsa_population or get_fred_series, and 'entity id' is an undefined abstraction that leaves the target of the lookup ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives. The agent is not told what an 'entity id' is or where one comes from, nor when this HUD-specific rent data is preferable to the other data-retrieval siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return BLS unemployment rate for an area code.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | US |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It states the data source (BLS) but discloses nothing about return format, data recency, caching, or error behavior for an unknown area.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with no waste and the key information front-loaded. Could afford to add a brief parameter hint without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be explained, but the 0% parameter coverage and absent annotations leave the caller guessing about the 'area' input and the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the 'area' parameter, its format, valid values, or what the 'US' default means. With low coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (return) and resource (BLS unemployment rate). Does not distinguish from siblings like get_cpi or get_fred_series, but the resource name is self-evidently distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no mention of alternatives, no exclusions. An agent must infer context entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_cbsa_populationget_cpiget_fred_seriesget_hud_fmrget_unemployment_rateScored across 5 tools
Most tools target distinct metrics (population, rent, unemployment, CPI), but get_fred_series is a generic catch-all that can fetch the same BLS/CPI series as the specialized tools, creating overlap and potential misselection.
All tools follow a consistent get_<metric> snake_case pattern, making the naming predictable and easy to parse.
Five tools is well-scoped for a focused statistical data server; each tool earns its place without bloat or extreme thinness.
Core economic indicators (population, rent, unemployment, CPI, generic FRED) are covered, but there is no way to list available series, sources, or metadata, which limits discoverability.
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
Housing Intel MCP — Meta-pack that chains FRED, BLS, ATTOM, and HUD APIs
75 MCP tools: SEC financials, FRED economics, IRS 990, FDA, FX, UK Companies House.
Macro data for AI agents: GDP, inflation, unemployment and more (World Bank, US BLS). No keys.
