Optionally uses the OpenAI API to enhance semantic search over HICAR code and documentation (requires 'hicar-mcp[api]' install).
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., "@hicar-mcp list all namelist options for the microphysics group"
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.
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?".
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-mcpThe 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: mcp-dalamud
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 serveTo 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" } } } }Feature | Needs | Without it |
Namelist / scheme / variable / docs lookup, static validation & generation | nothing (bundled) | — |
|
| source tools report how to enable |
| a compiled | static validation only |
|
| falls back to lexical search |
Higher-quality semantic (live rebuild) |
| local model |
Run hicar-mcp doctor to see exactly what was discovered and what is degraded.
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.
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/HICARPublished to the official MCP Registry as io.github.HICAR-Model/hicar-mcp.
The line below lets the registry verify that this PyPI package and the registry
entry have the same owner; do not remove it.
Lexical search over HICAR source (.F90) and docs. Requires HICAR_REPO (live mode) for source; bundled mode searches docs only.
Inputs: query (required), regex, max_results.
Parse a namelist and annotate every option with its description, type, default and allowed values; flag any validation issues.
Inputs: content (required).
Find Fortran symbols (module/subroutine/function/type) by name. Requires HICAR_REPO (live mode).
Inputs: name (required), kind.
Generate a namelist ('full' or 'minimal') with optional physics scheme selections. With use_binary, delegate to HICAR --gen-nml instead.
Inputs: mp, sm, lsm, pbl, +7 more.
Return a documentation page by file name or title.
Inputs: name (required).
Return the contents of an example namelist.
Inputs: name (required).
Full metadata for a model variable (by netCDF name or kVARS member).
Inputs: name (required).
Full metadata for one namelist option: group, &block, type, default, allowed values, range, units and description.
Inputs: name (required).
List selectable schemes for a category (or selector like 'mp'), with codes, originating constants, and supported status.
Inputs: category (required). Returns: result
List HICAR documentation pages.
Inputs: no named parameters. Returns: result
List bundled example namelists.
Inputs: no named parameters. Returns: result
List kVARS model/output variables (optionally substring-filtered).
Inputs: filter. Returns: result
List HICAR namelist groups (&blocks) with option counts.
Inputs: no named parameters. Returns: result
List namelist options, optionally filtered to one group.
Inputs: group. Returns: result
List physics-scheme categories (microphysics, pbl, radiation, ...).
Inputs: no named parameters. Returns: result
Read HICAR source by file path (repo-rooted, line range) or by symbol name. Requires HICAR_REPO (live mode).
Inputs: end, path, start, symbol.
Resolve a scheme name or integer code within a category.
Inputs: value (required), category (required).
Search the documentation (substring, with doc + line refs).
Inputs: query (required), max_results. Returns: result
Search example namelists for a substring.
Inputs: query (required). Returns: result
Search model variables by name/standard_name/description.
Inputs: query (required). Returns: result
Search namelist options by name/description (substring).
Inputs: query (required), group. Returns: result
Natural-language semantic search over HICAR code + docs. Falls back to lexical search if the embedding model isn't available.
Inputs: query (required), k, kind.
Report server mode, discovered paths, artifact/HICAR version, and which optional features (binary, ripgrep, semantic) are active.
Inputs: no named parameters.
Validate a namelist string. Static checks always run (unknown groups/options, bad enum values, out-of-range, type/per-nest issues). If use_binary and a compiled HICAR is available, also run --check-nml.
Inputs: content (required), use_binary.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 24 tools
Each tool targets a distinct resource or action, with clear descriptions. The multiple search tools (code_search, search_docs, etc.) could be confused, but their descriptions specify different domains (source code vs. docs vs. model variables), reducing ambiguity.
Tool names follow a verb_noun pattern, but there is inconsistency between 'get_' and 'list_' for related resources (e.g., get_model_variable vs. list_model_variables) and some names include 'tool' (generate_namelist_tool) or are noun_noun (server_status). Still, the pattern is mostly predictable.
With 24 tools, the count is on the high side of reasonable, but it is justified by the complexity of the HICAR model domain, covering code, namelist, variables, physics, and documentation aspects without being excessive.
The tool set provides comprehensive coverage for namelist generation, validation, variable metadata, physics scheme resolution, documentation, and source code access. Minor gaps exist (e.g., no tool to modify source or run the model), but these are likely out of scope.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
AI-callable calculators and engineering models with real formulas. No hallucinated math.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Bring your Knacco library into your AI tool: browse, search, read guides and download files.
