armstat-mcp

ArmStatBank holds 814 official statistical tables for Armenia — GDP, inflation, population, poverty, transport, environment. It is also close to unusable: navigation is opaque ?nid= query strings, and there is no working search. Finding one table is a twenty-minute job.

This is a remote MCP server that closes that gap. It ships a pre-crawled catalog of every table, so an AI assistant can find the right one in a single call, then fetch the actual figures live. Every result carries the date ArmStat last updated that table, so stale series are visible rather than quietly presented as current.

Built for journalists, analysts, researchers and civic technologists working with Armenian data.

ArmStatBank | Issue Tracker

Features

• Keyword search over all 814 tables — no upstream calls, so it is instant and cannot be rate-limited

• Live data retrieval as JSON-stat 2.0, Armenian or English labels

• Staleness always visible — every hit reports when ArmStat last updated it

• Stateless — no database, no session store, runs on Cloudflare Workers' free tier

• Self-maintaining — a weekly GitHub Action re-crawls the catalog and refuses to publish a truncated one

Related MCP server: SCB MCP Server

Contents

• Quick Start

• Known Limitations

• Changelog

• FAQ

• Contributing

• License

• Support

Quick Start

Requirements

• Node.js 20 or later

• A free Cloudflare account (deployment only)

Setup Instructions

1. Clone and install:

   git clone https://github.com/mheryerznkanyan/armstat-mcp.git
   cd armstat-mcp
   npm install

2. Verify the bundled catalog:

   npm test

   Expected: ok — 814 tables, top hit "Unemployment Rate by indicators and years"

Run Instructions

1. Start a local server:

   npm run dev

2. Confirm it is serving:

   curl http://localhost:8787/health

   Expected: ok, 814 tables

Build Instructions

Deploy to Cloudflare Workers:

npx wrangler deploy

Then add https://<your-worker>.workers.dev/mcp as a custom connector in Claude. No authentication — the upstream API requires none, so neither does this.

Usage Examples

Ask your assistant questions in plain language:

• "What has Armenian inflation done since 2020?"

• "Show me GDP per capita under SNA 2008."

• "Compare poverty levels across marzes."

• "What are air pollutant emissions per capita?"

Behind the scenes it calls three tools:

Direct protocol call:

curl -X POST http://localhost:8787/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"find_indicator","arguments":{"query":"consumer price index"}}}'

Known Limitations

These are properties of the upstream API, discovered by testing it. All are handled in src/search.mjs, but they shape what is possible.

• Rate limit: 10 calls per 10 seconds. Over the limit ArmStatBank drops the connection — no 429, no status code. A naive client reads this as "empty folder" and silently under-reports. This cost this project 176 tables once; npm test now fails if the catalog is short.

• A dataset's own updated field is unreliable. One CPI table reports 2013-04-05 inside the payload while the catalog says 2026-07-08. Trust the catalog.

• GDP exists under two standards. SNA 1993 tables froze in 2022; the live series is SNA 2008 (50 tables, current to 2026). Searches hit both, and the numbers are not comparable. Check the title before quoting.

• 69 of 814 tables have not been updated since 2024; the oldest is 2017.

• Foreign trade is nearly absent — 3 tables. Detailed trade data lives in separate systems on armstat.am (?nid=148, ?nid=159, ?nid=160).

• Government Finances has 1 table. Budget data is effectively not here.

• Not in the API at all: publications and PDFs, microdata, methodology notes.

• armdevinfo.am no longer resolves.

Changelog

See our releases.

Frequently Asked Questions (FAQ)

1. Why bundle the catalog instead of searching live?

   • ArmStatBank has no search endpoint, and its rate limit makes crawling at query time impossible. Bundling makes search instant and free.

2. How current is the catalog?

   • A GitHub Action re-crawls it weekly. Table data is always fetched live, so only the list of tables can lag — and new tables are rare.

3. Does this need an API key?

   • No. The upstream API is unauthenticated.

4. Can I use the data commercially?

   • The data belongs to the Statistical Committee of the Republic of Armenia. We could find no licence or terms-of-use page on their site. The Apache 2.0 licence here covers this software only, not ArmStat's data. Contact support@armstat.am before redistributing.

Contributing

Interested in contributing? Please see CONTRIBUTING.md.

For guidance on how to interact with our community, see CODE_OF_CONDUCT.md.

License

Licensed under the Apache License 2.0. See LICENSE.

This licence covers the software in this repository. Statistical data retrieved through it belongs to the Statistical Committee of the Republic of Armenia.

Support

Key point of contact: @mheryerznkanyan

For bugs and feature requests, please open an issue.