# mineralfyi

[![PyPI version](https://agentgif.com/badge/pypi/mineralfyi/version.svg)](https://pypi.org/project/mineralfyi/)
[![Python](https://img.shields.io/pypi/pyversions/mineralfyi)](https://pypi.org/project/mineralfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/mineralfyi/)

Python API client and CLI for minerals, crystal systems, and geological classification. Access 6,215 minerals across 10 mineral classes and 7 crystal systems — with chemical formulas, Mohs hardness, specific gravity, luster, streak, cleavage, and fracture data from 198 countries. Zero dependencies.

Extracted from [MineralFYI](https://mineralfyi.com/), a mineralogy reference platform with 162 glossary terms, 65 educational guides, and comparison tools for geologists, mineral collectors, educators, and developers building Earth science applications.

> **Explore minerals at [mineralfyi.com](https://mineralfyi.com/)** — browse the [mineral encyclopedia](https://mineralfyi.com/minerals/), explore [crystal systems](https://mineralfyi.com/crystal-systems/), study [mineral classes](https://mineralfyi.com/classes/), and read the [mineralogy glossary](https://mineralfyi.com/glossary/).

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/mineralfyi/main/demo.gif" alt="mineralfyi demo — mineral lookup, crystal system browsing, and Mohs hardness comparison in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Crystal Systems](#crystal-systems)
  - [Mineral Classes](#mineral-classes)
  - [Mineral Identification Properties](#mineral-identification-properties)
  - [Geographic Distribution](#geographic-distribution)
  - [Mineral Comparisons](#mineral-comparisons)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Minerals](#learn-more-about-minerals)
- [Also Available](#also-available)
- [Science FYI Family](#science-fyi-family)
- [FYIPedia Developer Tools](#fyipedia-developer-tools)
- [License](#license)

## Install

```bash
pip install mineralfyi                # Core (zero deps)
pip install "mineralfyi[cli]"         # + Command-line interface (typer, rich)
pip install "mineralfyi[mcp]"         # + MCP server for AI assistants
pip install "mineralfyi[api]"         # + HTTP client for mineralfyi.com API
pip install "mineralfyi[all]"         # Everything
```

Or run instantly without installing:

```bash
uvx --from mineralfyi mineralfyi search quartz
```

## Quick Start

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Look up any mineral — 6,215 minerals in the database
    quartz = api.get_mineral("quartz")
    print(quartz["name"])             # Quartz
    print(quartz["formula"])          # SiO2
    print(quartz["hardness"])         # 7.0
    print(quartz["crystal_system"])   # trigonal
    print(quartz["luster"])           # vitreous
    print(quartz["streak"])           # White
    print(quartz["cleavage"])         # None
    print(quartz["fracture"])         # Conchoidal

    # Browse crystal systems and mineral classes
    crystal_systems = api.list_crystal_systems()
    classes = api.list_classes()
```

## What You Can Do

### Crystal Systems

All crystalline minerals form in one of **7 crystal systems**, defined by the symmetry of their unit cell — the smallest repeating unit of the crystal lattice. Crystal system is the most fundamental classification in mineralogy, determining optical properties, cleavage planes, and crystal habit.

| Crystal System | Axes | Angles | Mineral Count | Examples |
|---------------|------|--------|---------------|---------|
| **Cubic (Isometric)** | a = b = c | All 90 degrees | — | Diamond, Pyrite, Halite, Garnet, Galena |
| **Hexagonal** | a1 = a2 = a3, c | 120 degrees / 90 degrees | — | Beryl, Apatite, Graphite, Molybdenite |
| **Trigonal** | a1 = a2 = a3, c | 120 degrees / 90 degrees | — | Quartz, Calcite, Corundum, Tourmaline, Hematite |
| **Tetragonal** | a = b, c | All 90 degrees | — | Zircon, Rutile, Cassiterite, Wulfenite |
| **Orthorhombic** | a, b, c all different | All 90 degrees | — | Topaz, Olivine, Barite, Aragonite, Sulfur |
| **Monoclinic** | a, b, c all different | Two 90 degrees, one oblique | — | Gypsum, Orthoclase, Augite, Epidote |
| **Triclinic** | a, b, c all different | No right angles | — | Plagioclase, Kyanite, Turquoise, Rhodonite |

The cubic system has the highest symmetry (48 symmetry elements), while triclinic has the lowest (2 elements). Most rock-forming minerals crystallize in the monoclinic, orthorhombic, or trigonal systems.

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # List all 7 crystal systems
    systems = api.list_crystal_systems()
    for s in systems["results"]:
        print(s["slug"], s["name"])
        # cubic, Cubic (Isometric)
        # hexagonal, Hexagonal
        # monoclinic, Monoclinic
        # orthorhombic, Orthorhombic
        # tetragonal, Tetragonal
        # triclinic, Triclinic
        # trigonal, Trigonal

    # Get crystal system detail
    cubic = api.get_crystal_system("cubic")
    print(cubic)
```

Learn more: [Crystal Systems](https://mineralfyi.com/crystal-systems/) · [Mineralogy Glossary](https://mineralfyi.com/glossary/) · [Mineral Guides](https://mineralfyi.com/guides/)

### Mineral Classes

Minerals are grouped into **10 chemical classes** based on their dominant anion or anionic group. The Dana classification system (first published 1837, now in its 8th edition) is the standard used by MineralFYI.

| Class | Description | Notable Minerals |
|-------|-------------|-----------------|
| **Native Elements** | Uncombined elements | Gold, Silver, Copper, Diamond, Sulfur |
| **Sulfides & Sulfosalts** | Metal-sulfur bonds | Pyrite, Galena, Chalcopyrite, Sphalerite |
| **Halides** | Metal-halogen bonds | Halite (NaCl), Fluorite (CaF2) |
| **Oxides & Hydroxides** | Metal-oxygen bonds | Hematite, Magnetite, Corundum, Goethite |
| **Carbonates & Nitrates** | CO3 or NO3 groups | Calcite, Dolomite, Malachite, Azurite |
| **Borates** | BO3 or BO4 groups | Borax, Ulexite, Colemanite |
| **Sulfates, Chromates, Molybdates** | SO4, CrO4, MoO4 groups | Gypsum, Barite, Celestine, Wulfenite |
| **Phosphates, Arsenates, Vanadates** | PO4, AsO4, VO4 groups | Apatite, Turquoise, Vanadinite |
| **Silicates** | SiO4 tetrahedra | Quartz, Feldspar, Mica, Olivine, Garnet |
| **Organic Minerals** | Carbon-based compounds | Whewellite, Mellite, Amber (borderline) |

Silicates are by far the most abundant class, making up approximately 90% of the Earth's crust. They are further subdivided by SiO4 tetrahedra arrangement: nesosilicates (isolated), sorosilicates (pairs), cyclosilicates (rings), inosilicates (chains), phyllosilicates (sheets), and tectosilicates (frameworks).

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # List all 10 mineral classes
    classes = api.list_classes()
    for c in classes["results"]:
        print(c["slug"], c["name"])

    # Get class detail with member minerals
    silicates = api.get_classe("silicates")
    print(silicates)
```

Learn more: [Mineral Classes](https://mineralfyi.com/classes/) · [Mineralogy Glossary](https://mineralfyi.com/glossary/)

### Mineral Identification Properties

Every mineral in the database includes the physical and optical properties used in standard geological identification. These are the properties a geologist tests in the field and laboratory.

| Property | What It Measures | Example (Quartz) |
|----------|------------------|-------------------|
| **Chemical Formula** | Composition | SiO2 |
| **Mohs Hardness** | Scratch resistance (1-10) | 7.0 |
| **Specific Gravity** | Density relative to water | 2.65 |
| **Crystal System** | Lattice symmetry | Trigonal |
| **Luster** | Surface light reflection | Vitreous |
| **Streak** | Powder color on porcelain | White |
| **Cleavage** | Preferred breaking planes | None |
| **Fracture** | Breaking pattern (non-cleavage) | Conchoidal |
| **Transparency** | Light transmission | Transparent |
| **Crystal Habit** | Typical growth form | Prismatic, massive, druzy |
| **Color** | Visual appearance | Colorless, white, purple, pink, brown, black |

The **Mohs hardness scale** (developed by Friedrich Mohs in 1812) ranks minerals from 1 (talc) to 10 (diamond). It is a relative scale — diamond (10) is roughly 4 times harder than corundum (9), while the jump from talc (1) to gypsum (2) is small. A steel knife has hardness ~5.5, a copper coin ~3.5, and a fingernail ~2.5.

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Look up quartz — second most abundant crustal mineral
    quartz = api.get_mineral("quartz")
    print(quartz["formula"])          # SiO2
    print(quartz["hardness"])         # 7.0
    print(quartz["specific_gravity"]) # 2.65
    print(quartz["crystal_system"])   # trigonal
    print(quartz["luster"])           # vitreous
    print(quartz["streak"])           # White
    print(quartz["cleavage"])         # None
    print(quartz["fracture"])         # Conchoidal
    print(quartz["transparency"])     # transparent
    print(quartz["crystal_habit"])    # Prismatic, massive, druzy
```

Learn more: [Mineral Encyclopedia](https://mineralfyi.com/minerals/) · [Mineral Guides](https://mineralfyi.com/guides/)

### Geographic Distribution

MineralFYI tracks mineral occurrences across **198 countries**, connecting minerals to their type localities and notable collection sites. Geographic provenance is important for both scientific classification (type locality defines the mineral species) and collector value.

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Browse 198 countries with mineral occurrences
    countries = api.list_countries()
    print(countries["count"])  # 198

    # Get country detail with associated minerals
    detail = api.get_country("brazil")
```

Learn more: [Countries](https://mineralfyi.com/countries/) · [Mineral Guides](https://mineralfyi.com/guides/)

### Mineral Comparisons

Compare two minerals side-by-side across all identification properties. Pre-computed comparisons highlight differences in hardness, crystal system, luster, and chemical composition for commonly confused mineral pairs (e.g., quartz vs. calcite, pyrite vs. gold).

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    # Browse mineral comparisons
    comparisons = api.list_comparisons(limit=5)
    for comp in comparisons["results"]:
        print(comp["slug"])
```

Learn more: [Mineral Comparisons](https://mineralfyi.com/comparisons/) · [Mineralogy Glossary](https://mineralfyi.com/glossary/)

## Command-Line Interface

```bash
pip install "mineralfyi[cli]"

mineralfyi search quartz             # Search minerals by name
mineralfyi search "iron oxide"       # Search by composition
mineralfyi search fluorite           # Search by mineral name
```

## MCP Server (Claude, Cursor, Windsurf)

Add mineral lookup tools to any AI assistant that supports [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
pip install "mineralfyi[mcp]"
```

Add to your `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "mineralfyi": {
            "command": "uvx",
            "args": ["--from", "mineralfyi[mcp]", "python", "-m", "mineralfyi.mcp_server"]
        }
    }
}
```

## REST API Client

```bash
pip install "mineralfyi[api]"
```

```python
from mineralfyi.api import MineralFYI

with MineralFYI() as api:
    minerals = api.list_minerals()                 # GET /api/v1/minerals/
    quartz = api.get_mineral("quartz")             # GET /api/v1/minerals/quartz/
    systems = api.list_crystal_systems()           # GET /api/v1/crystal-systems/
    classes = api.list_classes()                    # GET /api/v1/classes/
    countries = api.list_countries()                # GET /api/v1/countries/
    results = api.search("feldspar")               # GET /api/v1/search/?q=feldspar
```

### Example

```bash
curl -s "https://mineralfyi.com/api/v1/minerals/quartz/"
```

```json
{
  "name": "Quartz",
  "slug": "quartz",
  "formula": "SiO2",
  "crystal_system": "trigonal",
  "mineral_class": "silicates",
  "hardness": "7.0",
  "specific_gravity": "2.65",
  "color": "Colorless, white, purple, pink, brown, black",
  "luster": "vitreous",
  "streak": "White",
  "cleavage": "None",
  "fracture": "Conchoidal",
  "transparency": "transparent"
}
```

Full API documentation at [mineralfyi.com/developers/](https://mineralfyi.com/developers/).

## API Reference

| Method | Description |
|--------|-------------|
| `list_minerals(**params)` | List all 6,215 minerals with pagination |
| `get_mineral(slug)` | Get mineral detail with full identification properties |
| `list_crystal_systems(**params)` | List all 7 crystal systems |
| `get_crystal_system(slug)` | Get crystal system detail |
| `list_classes(**params)` | List all 10 mineral classes |
| `get_classe(slug)` | Get mineral class detail with member minerals |
| `list_countries(**params)` | List 198 countries with mineral occurrences |
| `get_country(slug)` | Get country detail |
| `list_comparisons(**params)` | List mineral comparisons |
| `get_comparison(slug)` | Get side-by-side comparison |
| `list_glossary(**params)` | List 162 mineralogy glossary terms |
| `get_term(slug)` | Get glossary term definition |
| `list_guides(**params)` | List 65 educational guides |
| `get_guide(slug)` | Get guide content |
| `search(query)` | Search across all mineral content |

## Learn More About Minerals

- **Browse**: [Mineral Encyclopedia](https://mineralfyi.com/minerals/) · [Crystal Systems](https://mineralfyi.com/crystal-systems/) · [Mineral Classes](https://mineralfyi.com/classes/) · [Countries](https://mineralfyi.com/countries/)
- **Compare**: [Mineral Comparisons](https://mineralfyi.com/comparisons/)
- **Reference**: [Mineralogy Glossary](https://mineralfyi.com/glossary/)
- **Guides**: [Educational Guides](https://mineralfyi.com/guides/)
- **API**: [REST API Docs](https://mineralfyi.com/developers/) · [OpenAPI Spec](https://mineralfyi.com/api/v1/)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install mineralfyi` | [npm](https://www.npmjs.com/package/mineralfyi) |
| **MCP** | `uvx --from "mineralfyi[mcp]" python -m mineralfyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Science FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — physical sciences, chemistry, geology, astronomy, and materials.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| chemfyi | [PyPI](https://pypi.org/project/chemfyi/) | [npm](https://www.npmjs.com/package/chemfyi) | Periodic table, 500 compounds, 371 reactions — [chemfyi.com](https://chemfyi.com/) |
| alloyfyi | [PyPI](https://pypi.org/project/alloyfyi/) | [npm](https://www.npmjs.com/package/alloyfyi) | 765 metal alloys, 12 families, compositions — [alloyfyi.com](https://alloyfyi.com/) |
| gemfyi | [PyPI](https://pypi.org/project/gemfyi/) | [npm](https://www.npmjs.com/package/gemfyi) | 442 gemstones, Mohs scale, grading — [gemfyi.com](https://gemfyi.com/) |
| starfyi | [PyPI](https://pypi.org/project/starfyi/) | [npm](https://www.npmjs.com/package/starfyi) | 119,602 stars, 6,128 exoplanets, 13,305 deep-sky objects — [starfyi.com](https://starfyi.com/) |
| **mineralfyi** | [PyPI](https://pypi.org/project/mineralfyi/) | [npm](https://www.npmjs.com/package/mineralfyi) | **6,215 minerals, 7 crystal systems — [mineralfyi.com](https://mineralfyi.com/)** |

## FYIPedia Developer Tools

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| colorfyi | [PyPI](https://pypi.org/project/colorfyi/) | [npm](https://www.npmjs.com/package/@fyipedia/colorfyi) | Color conversion, WCAG contrast, harmonies — [colorfyi.com](https://colorfyi.com/) |
| emojifyi | [PyPI](https://pypi.org/project/emojifyi/) | [npm](https://www.npmjs.com/package/emojifyi) | Emoji encoding & metadata for 3,953 emojis — [emojifyi.com](https://emojifyi.com/) |
| symbolfyi | [PyPI](https://pypi.org/project/symbolfyi/) | [npm](https://www.npmjs.com/package/symbolfyi) | Symbol encoding in 11 formats — [symbolfyi.com](https://symbolfyi.com/) |
| unicodefyi | [PyPI](https://pypi.org/project/unicodefyi/) | [npm](https://www.npmjs.com/package/unicodefyi) | Unicode lookup with 17 encodings — [unicodefyi.com](https://unicodefyi.com/) |
| fontfyi | [PyPI](https://pypi.org/project/fontfyi/) | [npm](https://www.npmjs.com/package/fontfyi) | Google Fonts metadata & CSS — [fontfyi.com](https://fontfyi.com/) |
| distancefyi | [PyPI](https://pypi.org/project/distancefyi/) | [npm](https://www.npmjs.com/package/distancefyi) | Haversine distance & travel times — [distancefyi.com](https://distancefyi.com/) |
| timefyi | [PyPI](https://pypi.org/project/timefyi/) | [npm](https://www.npmjs.com/package/timefyi) | Timezone ops & business hours — [timefyi.com](https://timefyi.com/) |
| namefyi | [PyPI](https://pypi.org/project/namefyi/) | [npm](https://www.npmjs.com/package/namefyi) | Korean romanization & Five Elements — [namefyi.com](https://namefyi.com/) |
| unitfyi | [PyPI](https://pypi.org/project/unitfyi/) | [npm](https://www.npmjs.com/package/unitfyi) | Unit conversion, 220 units — [unitfyi.com](https://unitfyi.com/) |
| holidayfyi | [PyPI](https://pypi.org/project/holidayfyi/) | [npm](https://www.npmjs.com/package/holidayfyi) | Holiday dates & Easter calculation — [holidayfyi.com](https://holidayfyi.com/) |
| cocktailfyi | [PyPI](https://pypi.org/project/cocktailfyi/) | — | Cocktail ABV, calories, flavor — [cocktailfyi.com](https://cocktailfyi.com/) |
| fyipedia | [PyPI](https://pypi.org/project/fyipedia/) | — | Unified CLI: `fyi mineral info quartz` — [fyipedia.com](https://fyipedia.com/) |
| fyipedia-mcp | [PyPI](https://pypi.org/project/fyipedia-mcp/) | — | Unified MCP hub for AI assistants — [fyipedia.com](https://fyipedia.com/) |

## License

MIT
