unhcr

The UNHCR MCP Server exposes a set of tools to query refugee statistics and related data from the UNHCR API. It includes capabilities to fetch population statistics, demographic breakdowns by age and gender, search for country ISO3 codes, retrieve time series data, and obtain asylum decision information. These tools are exposed as MCP commands such as get_population_statistics, get_demographics, search_countries, get_time_series, and get_asylum_decisions, allowing you to integrate UNHCR data into your AI assistants or workflows. To use, run the server locally with Node.js and issue the supported commands through your MCP interface orClaude Desktop integration as demonstrated in the configuration sample.

The server is designed to be simple to query: provide the required parameters (for example year, country_code, population_type, or start_year/end_year) and receive structured data in response. It leverages the UNHCR API v2 for underlying data access, so responses follow the API’s conventions and data definitions. You can combine multiple commands to build dashboards or assistive tools that track refugee statistics and asylum trends over time.

Prerequisites:

• Node.js (LTS version) and npm installed on your system
• Git (optional, if cloning from a repository)

Installation steps:

1. Clone or download the repository: git clone https://github.com/your-org/unhcr-mcp-server.git cd unhcr-mcp-server

2. Install dependencies: npm install

3. Run the server locally: node index.js

4. Optional: configure your MCP client (e.g., Claude Desktop) to point to the local server endpoint. Example configuration (adjust path to your index.js): { "mcpServers": { "unhcr": { "command": "node", "args": ["/path/to/unhcr-mcp-server/index.js"] } } }

Notes and tips:

• The server requires internet access to fetch data from the UNHCR API v2. Ensure network access is permitted.
• The available tools are: get_population_statistics, get_demographics, search_countries, get_time_series, and get_asylum_decisions. Each tool has specific parameters as described in the README.
• For production hosting (e.g., mcp.so), upload your server files and configure the endpoint as per the hosting provider's instructions.
• If you encounter API rate limits or authentication requirements from UNHCR, ensure you follow their usage policies and any required API keys or tokens (if applicable).
• When using time series data, you can specify a range with start_year and end_year to obtain longitudinal statistics.
• If you need to update the server with new data fields or endpoints, modify the underlying code and redeploy the server.