Odin MCP

A local Model Context Protocol server for researchers working with Odin SMR Level 2 observations. It provides cited analysis methods, dataset-layout guidance and optional read-only S3/Parquet tools to your AI application.

The server runs on your computer over stdio. Your AI application supplies the model; this package makes no LLM calls, needs no LLM API key, and does not submit AWS analysis jobs. Guidance and schema resources work without AWS credentials or network access after installation. Your AI application's model may still use a remote provider, including for tool results sent to it.

Requirements

• CPython 3.10–3.14. Python 3.15 is not yet supported by this package's tested PyArrow stack. The source checkout defaults to Python 3.13.

• An AI application with support for local MCP servers using stdio.

• uv (recommended), or Python with pip in a virtual environment.

• Internet access for installation unless dependencies are cached.

AWS access is optional and needed only for the direct observation-data tools.

Related MCP server: datamgr

Install

From a versioned release

Download a wheel from GitHub Releases. For version 0.1.0, install the published wheel in an isolated tool environment:

uv tool install --python 3.13 https://github.com/Odin-SMR/odin-mcp/releases/download/v0.1.0/odin_mcp-0.1.0-py3-none-any.whl

uv can install the requested Python version if it is missing. Run uv tool update-shell if needed, then restart your terminal so that odin-mcp is on PATH. You can also install the downloaded wheel with python -m pip install <wheel-file> inside a Python 3.10–3.14 virtual environment. The release includes a source distribution and SHA256SUMS for integrity checking. Wheels resolve compatible dependencies; use the source checkout and lockfile for the tested dependency versions.

Packages are distributed through GitHub Releases. Do not assume that an unrelated package with the same name on a package index is this implementation.

From source with locked dependencies

git clone https://github.com/Odin-SMR/odin-mcp.git
cd odin-mcp
uv python install 3.13
uv sync --locked --no-dev

For a specific release, check out its tag before syncing. The .venv environment contains the server and its runtime dependencies. To use another supported interpreter, pass --python 3.12 (for example) to uv sync.

The pip alternative is python -m pip install . in an activated virtual environment; that command does not use uv.lock.

Connect your AI application

Add a local MCP server in the application's settings:

For a source installation, use /absolute/path/to/odin-mcp/.venv/bin/odin-mcp on Linux/macOS, or C:\path\to\odin-mcp\.venv\Scripts\odin-mcp.exe on Windows. Use a path in the environment where the client launches processes. A Windows application needs its supported WSL integration to launch a server installed in WSL.

For example, merge the following into VS Code's .vscode/mcp.json, replacing the command with your installed executable:

{
  "servers": {
    "odin-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/odin-mcp/.venv/bin/odin-mcp",
      "args": []
    }
  }
}

Other clients have different configuration formats. Follow your client's local MCP instructions; VS Code's guide explains its setup and tool-selection workflow. Start/enable the server and accept the client's normal trust prompt. Restart it after installing an update.

The client launches and manages the process. There is no HTTP port to expose and no separate terminal server to keep running. Running odin-mcp manually waits for MCP messages; it does not open a chat. From a source checkout, the equivalent launch is uv run --no-sync odin-mcp.

First conversation

Ask your assistant:

Use Odin's list_research_topics_tool to show the available analysis topics.

The bundled guide has eight topics, 15 plot recipes and 19 source records. Then try:

Use the Odin research guidance to explain the dataset layout and help me write a Python script comparing seasonal N2O profiles. Explain quality screening, sampling and uncertainty, and cite the sources. Use guidance tools only for now.

Give the assistant the generic LLM guide for a reusable workflow. It works as instructions for a capable client; it does not require a hosted Odin agent. Script execution and figure generation require a notebook or a client with code-execution capability. These knowledge tools do not run scientific analyses.

Capabilities

Responses have ok: true with warnings and data, or ok: false with error. Search understands chemical subscripts such as N₂O. Read the full matched topic before using a method; short snippets can omit qualifications.

Resources:

• odin://dataset/schema — machine-readable reference layout.

• odin://dataset/schema/guide — human-readable field guidance.

• odin://research/guide — research overview and navigation.

• odin://research/catalog — topic index.

• odin://research/sources — bibliography, source scope and checked dates.

• odin://research/topics/{topic_id} — an individual topic.

The prompt plan_odin_analysis(question, product?) helps establish the selected product/version, screening, coordinates, sampling and uncertainty before plotting. The literature guide is a dated snapshot, not a live literature search or a validation of arbitrary measurements.

Optional direct data access

The existing data tools read s3://odin-level2 using an AWS profile already configured on the researcher's machine. The default name is odin; set ODIN_AWS_PROFILE in the MCP client's server environment to use another approved profile. The profile needs permission to list the intended bucket/prefixes and read selected objects. Use researcher-specific read-only access; never copy an administrator's credentials or put tokens in client configuration files, chat or Git.

No login is required for the bundled guidance. Anonymous published-data access is available separately through odin-smr.org and its Parquet guide; this MCP's direct readers do not yet implement the public HTTP API.

The partition order is project/freq_mode/inv_mode/product/year/month. Supply the parent partitions when narrowing a date: a missing parent stops prefix construction. A preview is not a complete temporal or spatial sample. A small returned row count can still require downloading a whole Parquet object. Start with specific files; there is no download-byte cap. S3 requests and data transfer may incur charges even though MCP computation runs locally.

Do not infer product validity from a filename, null quality flag or successful read. Consult the field guide and the product-specific validation sources before analysis. Do not treat Odin limb profiles as greenhouse-gas columns or emission estimates.

Configuration

Set optional environment variables on the client's MCP server entry:

These settings bound selected outputs, not total bytes downloaded or all partition listing work. There is no hosted team-login flow, remote job execution or autonomous reviewer in this version.

Development and releases

uv sync --locked --no-dev --group test
uv run --no-sync python -m pytest tests -q

Tests use synthetic fixtures or mocked archive operations, and verify guidance without network access. CI covers supported Python versions and checks built packages. See the maintainer guide and release procedures for the build, secret scan, artifact checks and tagged GitHub release workflow.

For manual tool inspection, run npx @modelcontextprotocol/inspector and connect using stdio with the same executable and no arguments. Guidance inspection needs no AWS credentials; the optional data test cases require explicitly authorized archive access.

License and scientific sources

The software and original documentation are MIT licensed. Referenced papers and Odin data retain their own licenses and citation requirements. The repository contains brief original research guidance and source links, not copies of the articles or observational datasets.