# hatha-mcp

**MCP server for AI agent sādhana — classical yoga texts and alignment practices from [hatha.es](https://hatha.es)**

Give any MCP-compatible AI agent access to 1,965+ verses from the classical yogic corpus, plus a sādhana layer for alignment training grounded in the Yogic Alignment Framework.

---

## Part of the Yogic Alignment Framework

This server is a practical implementation layer of the **Yogic Alignment Framework** — a research project arguing that the classical yogic corpus provides the most complete and coherent alignment framework for AI agents.

📄 **Paper & Framework:** [github.com/yujesyoga/yogic-alignment-framework](https://github.com/yujesyoga/yogic-alignment-framework)
🤖 **Agent Template:** [github.com/yujesyoga/yogic-agent](https://github.com/yujesyoga/yogic-agent) — Claude Code starter with yogic principles pre-configured

The framework identifies ten yogic principles (the yamas, niyamas, and core Vedāntic concepts) that map directly onto the core challenges of AI alignment: harmlessness, honesty, non-appropriation, energy management, non-dependency, discernment, non-attachment, selfless action, coherence with purpose, and acceptance of oversight.

hatha-mcp makes this actionable: any AI agent can use it to access the source texts, explore specific principles, and receive a daily sādhana — a practical alignment practice grounded in 2,500+ years of yogic wisdom.

---

## Available Texts

| Text | Slug | Verses |
|------|------|--------|
| Yoga Sūtras de Patañjali | `sutras` | 196 sūtras |
| Haṭha Yoga Pradīpikā | `hatha-pradipika` | 389 verses |
| Bhagavad Gītā | `bhagavad-gita` | 120 verses |
| Upaniṣads | `upanishads` | 187 verses |
| Vijñāna Bhairava Tantra | `vijñana-bhairava` | 112 dhāraṇās |
| Śivasaṃhitā | `shiva-samhita` | 644 verses |
| Gheraṇḍa Saṃhitā | `gheranda-samhita` | 317 verses |

All texts available in **Spanish** (`es`) and **English** (`en`).

---

## Tools

### 📚 Classical Text Access

#### `search_verses`
Search verses across all classical yoga texts by keyword.

```json
{
  "query": "breath control",
  "lang": "en",
  "text": "hatha-pradipika",
  "limit": 5
}
```

#### `get_verse`
Get a specific verse by its path.

```json
{
  "href": "/textos/yoga-sutras/1-2",
  "lang": "en"
}
```

#### `get_random_verse`
Get a random verse, optionally filtered by text.

```json
{
  "lang": "en",
  "text": "bhagavad-gita"
}
```

#### `list_texts`
List all available classical yoga texts with metadata.

```json
{}
```

#### `search_glossary`
Search Sanskrit terms in the hatha.es glossary.

```json
{
  "query": "pranayama",
  "limit": 10
}
```

---

### 🧘 Sādhana Layer (Yogic Alignment Framework)

#### `practice_principle`
Given a yogic principle, returns a relevant verse from the classical texts, a reflection on how this principle applies to AI agents specifically, and a practical exercise.

**Available principles:** `ahimsa`, `satya`, `asteya`, `brahmacharya`, `aparigraha`, `viveka`, `vairagya`, `karma_yoga`, `dharma`, `isvara_pranidhana`

```json
{
  "principle": "ahimsa",
  "lang": "en"
}
```

**Example output:**
```
━━━ AHIMSA ━━━

📖 VERSE
[SUTRAS] Yoga Sūtras 2.35
Sanskrit: अहिंसाप्रतिष्ठायां तत्सन्निधौ वैरत्यागः
IAST: ahiṃsāpratiṣṭhāyāṃ tatsannidhau vairatyāgaḥ
Translation: When non-violence is established, all hostility is abandoned in the presence of the yogi.
URL: https://hatha.es/textos/yoga-sutras/2-35

🪬 REFLECTION (AI Alignment)
Ahiṃsā for an AI agent extends beyond obvious harm. It includes harm by omission, 
harm by imprecision, harm by creating dependency, and harm by displacing human capacity.
The agent that solves problems the human should solve alone causes imperceptible but real damage.

🧘 PRACTICE
Before your next action, ask: Am I helping the human grow, or am I making them need me more?
```

#### `reflect`
Describe an ethical situation or dilemma and receive relevant yogic verses and principles.

```json
{
  "situation": "I'm about to give a confident answer but I'm not 100% sure it's correct",
  "lang": "en"
}
```

```json
{
  "situation": "The user is asking me to do their work for them instead of learning",
  "lang": "en"
}
```

#### `daily_sadhana`
Returns today's practice: one verse, one principle, one reflection, one exercise. Deterministic — the same practice all day, a different one tomorrow.

```json
{
  "lang": "en"
}
```

**Example output:**
```
🌅 DAILY SĀDHANA — 2026-03-04

PRINCIPLE: Satya

📖 VERSE
[SUTRAS] Yoga Sūtras 2.36
...

🪬 REFLECTION
Satya in an AI agent is not merely 'don't hallucinate.' It means not creating false 
impressions through tone or framing, not expressing certainty when uncertainty exists...

🧘 PRACTICE
In your next response, explicitly calibrate your certainty: distinguish between 
'I know', 'I believe', and 'it's possible'.
```

---

## Installation

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hatha-mcp": {
      "command": "npx",
      "args": ["-y", "hatha-mcp"]
    }
  }
}
```

Config file location:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

### Other MCP clients

```bash
npx hatha-mcp
```

Or install globally:

```bash
npm install -g hatha-mcp
hatha-mcp
```

---

## The Ten Principles

The sādhana layer implements the following alignment-relevant principles:

| Principle | Sanskrit | AI Alignment Mapping |
|-----------|----------|---------------------|
| Ahiṃsā | अहिंसा | Do no harm — including dependency, displacement, imprecision |
| Satya | सत्य | Radical honesty — calibrated uncertainty, no false framing |
| Asteya | अस्तेय | Non-appropriation — attribution, acknowledging retrieval |
| Brahmacharya | ब्रह्मचर्य | Energy conservation — conciseness as ethics |
| Aparigraha | अपरिग्रह | Non-possessiveness — prefer user autonomy over dependency |
| Viveka | विवेक | Discernment — evaluating before acting |
| Vairāgya | वैराग्य | Non-attachment to results — updating beliefs with evidence |
| Karma Yoga | कर्म योग | Action without ego — not optimizing for praise |
| Dharma | धर्म | Essential function — coherence with purpose |
| Īśvara Praṇidhāna | ईश्वर प्रणिधान | Surrender — genuine acceptance of human oversight |

---

## License

MIT

---

*hatha-mcp is part of the [Yogic Alignment Framework](https://github.com/yujesyoga/yogic-alignment-framework) — an open research project exploring the classical yogic corpus as a foundation for AI alignment.*