ICF MCP Server

MCP server for searching, browsing, and looking up ICF (International Classification of Functioning, Disability and Health) codes via the WHO ICD-API v2.

About

This server exposes the WHO ICF classification as a set of MCP tools and prompts so an LLM can resolve, validate, and enrich ICF codes during clinical reasoning — search by free text, browse the hierarchy, look up qualifier scales, parse qualified notations like d450.2.3, retrieve published Core Sets for 20 conditions, and emit FHIR/openEHR/OID interoperability metadata. It runs against either the public WHO ICD-API (OAuth2) or a local Docker container (no auth), and is intended for clinicians, informaticians, and researchers building ICF-aware tooling on top of Claude or other MCP clients.

Caution

Accuracy disclaimer — The ICF data returned by this server is sourced directly from the WHO ICD-API and is accurate at the point of retrieval. However, an LLM processes and presents these results to you, and in doing so may introduce inaccuracies — rephrasing terms, inferring relationships, or adding context that is not present in the original data. Always verify critical clinical information against the raw ICF codes and terms provided in the tool output.

Tools

Tool	Description
search_icf	Search ICF codes by query. Supports component filtering. Returns suggestions on no results.
get_icf_code	Get full details for a code (definition, inclusions, exclusions, hierarchy). Optionally inline qualifiers.
browse_icf_hierarchy	Browse top-level chapters or children of a code.
autocode_icf	Match free-text clinical descriptions to ICF codes. Supports top-N results.
get_related_codes	Get parents, siblings, and children of a code.
get_qualifiers	Get qualifier scales for any code (severity, performance/capacity, barrier/facilitator).
validate_icf_notation	Parse qualified notations like d450.2.3 into human-readable components.
get_icf_core_set	Get condition-specific ICF code lists (brief or comprehensive). See available conditions.
get_terminology_info	Get FHIR, openEHR, and OID interoperability metadata for a code.

Prompts

Prompt	Description
code_clinical_note	Guide structured ICF coding of a clinical narrative into a functional profile.
build_functional_profile	Build a comprehensive ICF profile from a condition and assessment findings using core sets.
map_to_fhir	Map ICF codes to FHIR R4 resources with proper coding and system URIs.
explore_domain	Guided exploration of an ICF domain for research or archetype development.

Setup

1. Build

npm install
npm run build

2. Choose an API backend

Option A: Local Docker container (recommended)

No API credentials needed. Faster and works offline after initial setup.

docker run -p 8088:80 \
  -e acceptLicense=true \
  -e saveAnalytics=false \
  -e include=2025-01_en \
  whoicd/icd-api

Set the environment variable:

WHO_API_BASE_URL=http://localhost:8088

Option B: Remote WHO API

Register at icd.who.int/icdapi to get credentials, then set:

WHO_CLIENT_ID=your_client_id
WHO_CLIENT_SECRET=your_client_secret

3. Register with Claude

Claude Code (global)

Local Docker:

claude mcp add icf -s user \
  -e WHO_API_BASE_URL=http://localhost:8088 \
  -- node /path/to/icf/build/index.js

Remote WHO API:

claude mcp add icf -s user \
  -e WHO_CLIENT_ID=your_client_id \
  -e WHO_CLIENT_SECRET=your_client_secret \
  -- node /path/to/icf/build/index.js

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Local Docker:

{
  "mcpServers": {
    "icf": {
      "command": "node",
      "args": ["/path/to/icf/build/index.js"],
      "env": {
        "WHO_API_BASE_URL": "http://localhost:8088"
      }
    }
  }
}

Remote WHO API:

{
  "mcpServers": {
    "icf": {
      "command": "node",
      "args": ["/path/to/icf/build/index.js"],
      "env": {
        "WHO_CLIENT_ID": "your_client_id",
        "WHO_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Environment Variables

Variable	Required	Default	Description
WHO_API_BASE_URL	No	https://id.who.int	API base URL. Set to http://localhost:8088 for local Docker.
WHO_API_RELEASE	No	2025-01	ICF release version.
WHO_CLIENT_ID	Remote only	—	OAuth2 client ID for WHO API.
WHO_CLIENT_SECRET	Remote only	—	OAuth2 client secret for WHO API.

A .env file in the working directory is loaded automatically.

ICF Qualified Notation

ICF codes can carry qualifier suffixes that rate severity or extent. The validate_icf_notation tool parses these into human-readable components.

Component	Format	Example	Meaning
Body Functions (b)	bXXX.severity	b280.2	Moderate pain
Body Structures (s)	sXXX.severity.nature.location	s730.3.2.1	Severe impairment, partial absence, right side
Activities (d)	dXXX.performance.capacity	d450.2.3	Moderate performance problem, severe capacity problem
Environment (e) — barrier	eXXX.severity	e110.2	Moderate barrier
Environment (e) — facilitator	eXXX+extent	e110+3	Substantial facilitator

Qualifier values: 0 = no problem, 1 = mild (5-24%), 2 = moderate (25-49%), 3 = severe (50-95%), 4 = complete (96-100%), 8 = not specified, 9 = not applicable.

ICF Core Sets

The get_icf_core_set tool provides published WHO ICF Core Sets for 20 conditions, available as brief (most relevant categories) or comprehensive (all relevant categories):

Condition	Condition	Condition	Condition
Ankylosing Spondylitis	Bipolar Disorder	Breast Cancer	Cerebral Palsy
Chronic Obstructive Pulmonary Disease	Chronic Pain	Depression	Diabetes Mellitus
Hearing Loss	Low Back Pain	Multiple Sclerosis	Obesity
Osteoarthritis	Osteoporosis	Rheumatoid Arthritis	Schizophrenia
Sleep Disorders	Spinal Cord Injury	Stroke	Traumatic Brain Injury

Search also matches aliases (e.g., "COPD", "CVA", "TBI", "RA").

Testing with the MCP Inspector

WHO_API_BASE_URL=http://localhost:8088 npx @modelcontextprotocol/inspector node build/index.js

Open the URL printed in the terminal, click Connect, go to Tools, then List Tools.

Example calls:

• search_icf — { "query": "walking" } or { "query": "pain", "component": "b" }
• get_icf_code — { "code": "b280" } or { "code": "d450", "include_qualifiers": true }
• browse_icf_hierarchy — {} (top-level) or { "code": "b2" }
• autocode_icf — { "text": "difficulty walking long distances" } or { "text": "severe back pain", "max_results": 3 }
• get_related_codes — { "code": "d450" }
• get_qualifiers — { "code": "d450" }
• validate_icf_notation — { "notation": "d450.2.3" } or { "notation": "e110+3" }
• get_icf_core_set — { "condition": "stroke" } or { "condition": "low back pain", "type": "comprehensive" }
• get_terminology_info — { "code": "d450" }