hatha-mcp

MCP server for AI agent sādhana — classical yoga texts and alignment practices from 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 🤖 Agent Template: 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.

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

get_verse

Get a specific verse by its path.

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

get_random_verse

Get a random verse, optionally filtered by text.

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

list_texts

List all available classical yoga texts with metadata.

{}

search_glossary

Search Sanskrit terms in the hatha.es glossary.

{
  "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

{
  "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.

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

{
  "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.

{
  "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:

{
  "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

npx hatha-mcp

Or install globally:

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 — an open research project exploring the classical yogic corpus as a foundation for AI alignment.