hicar-mcp

A Model Context Protocol (MCP) server that gives AI assistants structured, authoritative knowledge of the HICAR atmospheric model: every namelist option, the physics-scheme registry, the ~375-variable output catalog, the documentation, and the source code.

Point any MCP client (Claude Desktop, Claude Code, Cursor, …) at it and ask things like "what does the mp option do and what are its valid values?", "which microphysics schemes are supported?", "what units is pressure_i in?", "generate a minimal namelist using Morrison microphysics", or "where is the wind solver iterated?".

Install

pipx install "hicar-mcp[semantic]"      # recommended (isolated, with semantic search)
# or
uv tool install "hicar-mcp[semantic]"
# or, lightweight (no semantic search):
pip install hicar-mcp

The server ships with pre-extracted knowledge bundled in, so it works with zero configuration — you do not need a HICAR checkout or a compiled binary. Optional upgrades light up automatically (see Modes below).

Related MCP server: AI Book Agent MCP Server

Configure your MCP client

Claude Desktop / Cursor — add to the mcpServers block of the client config:

{
  "mcpServers": {
    "hicar": { "command": "hicar-mcp", "args": ["serve"] }
  }
}

Claude Code:

claude mcp add hicar -- hicar-mcp serve

To enable source-aware tools (code_search, find_symbol, read_source) and always-fresh metadata, point it at a HICAR checkout:

{ "mcpServers": { "hicar": {
    "command": "hicar-mcp", "args": ["serve"],
    "env": { "HICAR_REPO": "/abs/path/to/HICAR" } } } }

Modes & graceful degradation

Run hicar-mcp doctor to see exactly what was discovered and what is degraded.

Tools

Namelist: list_namelist_groups, list_namelist_options, get_namelist_option, search_namelist_options, validate_namelist, generate_namelist_tool, explain_namelist. Schemes: list_physics_categories, get_physics_schemes, resolve_physics_scheme. Variables: list_model_variables, get_model_variable, search_model_variables. Examples: list_example_namelists, get_example_namelist, search_example_namelists. Docs: list_docs, get_doc, search_docs. Code: code_search, find_symbol, read_source, semantic_search. Diagnostics: server_status.

Resources (hicar://…) and guided prompts (configure_hicar_run, debug_namelist_error, explain_physics_choice) are also provided.

How the knowledge stays current

The bundled artifacts are regenerated from HICAR source by CI on each HICAR release (a workflow in the HICAR repo dispatches to this one). To regenerate locally:

hicar-mcp regenerate --repo /path/to/HICAR

License

MIT. HICAR itself is licensed separately; see the HICAR repository.