mcpField
M
MANNA

MANNA

Local
github.com/NSF-Simons-CosmicAI-InstituteScience & Education4Updated 6d ago
Repository

About MANNA

MANNA is an MCP server for LLM clients querying astronomical archives through IVOA interfaces. It is intended for astronomy researchers and includes archive-specific notes, multi-step workflows, and asynchronous handling for large TAP results.

Key features

  1. 01Run TAP/ADQL queries
  2. 02Search images and catalog sources
  3. 03Resolve target names and query the registry
  4. 04Use multi-step archive workflows
  5. 05Consult and verify archive-specific notes
  6. 06Handle large TAP results asynchronously

Use cases

  1. 01Search for images or catalog sources by position
  2. 02Query astronomical data in IVOA archives
  3. 03Write ADQL with archive-specific field guidance
  4. 04Fetch large query results from a result URL

MCP support

MANNA exposes IVOA archive interfaces to LLM clients over MCP, including TAP/ADQL, SIA, cone search, registry queries, and name resolution.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "nsf-simons-cosmicai-institute-manna": {
      "command": "uvx",
      "args": [
        "manna-mcp"
      ],
      "env": {
        "MANNA_ARCHIVES": "<MANNA_ARCHIVES>",
        "MANNA_ALLOWED_HOSTS": "<MANNA_ALLOWED_HOSTS>",
        "MANNA_LOG_LEVEL": "<MANNA_LOG_LEVEL>",
        "MANNA_INLINE_ROW_LIMIT": "<MANNA_INLINE_ROW_LIMIT>"
      }
    }
  }
}
Run commanduvx manna-mcp
Environment variables to set
MANNA_ARCHIVESComma-separated archive short_names to activate (e.g. 'datalab,alma'). Unset means all.
MANNA_ALLOWED_HOSTSComma-separated hostnames the server may fetch. Unset means any public host.
MANNA_LOG_LEVELLogging verbosity.
MANNA_INLINE_ROW_LIMITMax rows returned inline before a result is promoted to an async job or truncated.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypimanna-mcp0.11.0

Tools

15

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
wavebandanyNoOptional. Return only archives in this waveband (case-insensitive), e.g. 'radio', 'optical', 'millimeter'. Combines with short_name (both must match).
short_nameanyNoOptional. Return only the archive with this short_name (case-insensitive), e.g. 'alma'. Use this when you already know which archive you want — it returns a single entry instead of the full set, saving context. Unknown names return an empty list (count: 0).

Details

From the project README

MANNA

PyPI Documentation CI License: MIT

MANNA (MCP Architecture for NOIRLab, NRAO, and additional Archives) is an MCP server that gives LLM clients such as Claude Code, Claude Desktop, and Jupyter AI access to astronomical archives through the standard IVOA interfaces: TAP/ADQL, SIA image search, cone search, the IVOA registry, and Sesame name resolution. It includes curated notes for NOIRLab Astro Data Lab, ALMA, CADC, ESO, Gaia, and SDSS, and can reach any archive listed in the IVOA registry.

Its tools fall into four groups:

  • Connections call the IVOA interfaces directly: resolve a target name, run an ADQL query, search for images or catalog sources by position, search the registry.
  • Workflow tools do a multi-step task in one call: resolve a target, pick an archive, run the search or count.
  • Result handling returns small results inline. A large TAP result becomes an async job, and the client receives a result URL and a pyvo snippet to fetch it. The server keeps nothing between requests.
  • Archive notes record each archive's quirks (missing columns, enum values, spatial-index hints) so the model sees them before writing ADQL. Every note has a check that re-verifies it.

Full documentation, including the reference for every tool, is at https://manna.readthedocs.io.

Installation

Python 3.12 or later. The PyPI distribution is manna-mcp; the import package and the command are both manna.

uvx manna-mcp --stdio        # run without installing: MCP over stdio
pip install manna-mcp        # or install it; `manna` then serves HTTP on :8000

The first launch downloads astropy and pyvo, which takes a while. Run uvx manna-mcp --stdio once in a terminal before adding it to a client with a short startup timeout.

The Docker image and the MCP Registry entry are described under Installation.

Connect a client

Claude Code:

claude mcp add manna -- uvx manna-mcp --stdio

Claude Desktop, or any client with a JSON config:

{"mcpServers": {"manna": {"command": "uvx", "args": ["manna-mcp", "--stdio"]}}}

For a shared HTTP server or Jupyter AI, run manna and point the client at http://localhost:8000/mcp/.

Guides: Claude Code, Claude Desktop, Jupyter AI, a first query.

Configuration

All settings are optional and are read from MANNA_* environment variables or a .env file. The two most often changed:

  • MANNA_ARCHIVES=datalab,alma limits which archives have curated notes. Unset means every archive except nrao, which is inactive until named here.
  • MANNA_INLINE_ROW_LIMIT=2000 and MANNA_INLINE_BYTE_LIMIT=262144 raise the inline result caps from their small-model defaults to suit a large context window such as Claude's.

Every setting is listed in the configuration guide. Adding or removing an archive is covered in the archives guide.

Development

git clone https://github.com/NSF-Simons-CosmicAI-Institute/manna
cd manna
uv sync
uv run pytest --record-mode=none   # offline replay of recorded archive traffic
uv run python -m manna             # server on http://localhost:8000

Feature branches are cut from dev and merged back by pull request. Tests, linting, recorded cassettes, the docs build, and releases are described under Contributing.

License

MIT. Developed by the NSF-Simons CosmicAI Institute.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.