themis-mcp 1.0.0

MCP server for THEMIS — Indian statutory law Q&A via local LLM (BNS, IPC, BNSS, BSA, RTI)

themis-mcp

MCP server for THEMIS — Indian statutory law Q&A via local LLM.

"Baked into weights, grounded by retrieval."

---

What is this?

An MCP (Model Context Protocol) server that wraps the themis-llm SDK, making Indian legal knowledge available to any MCP-compatible client (Claude Desktop, opencode, Cursor, etc.).

Supported laws:

• Bharatiya Nyaya Sanhita (BNS) 2023 — 358 sections
• Bharatiya Nagarik Suraksha Sanhita (BNSS) 2023 — 531 sections
• Bharatiya Sakshya Adhiniyam (BSA) 2023 — 170 sections
• Indian Penal Code (IPC) 1860 — 511 sections
• Right to Information Act (RTI) 2005 — 31 sections
• Consumer Protection Act (CPA) 2019 — 107 sections

---

Requirements

• Python 3.11+
• GPU with ~13GB VRAM (for local model inference)
• ~13GB disk space (for model weights)

---

Quick Start

Step 1: Install

pip install themis-mcp

Or with CLI extras:

pip install "themis-mcp[cli]"

Step 2: Configure your MCP client

Add to your MCP client config:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "themis": {
      "command": "themis-mcp"
    }
  }
}

opencode (opencode.json):

{
  "mcpServers": {
    "themis": {
      "command": "themis-mcp"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "themis": {
      "command": "themis-mcp"
    }
  }
}

Step 3: Use it

Ask legal questions in natural language:

> What does Section 302 of the BNS say about murder?

> What is the punishment for theft under the Bharatiya Nyaya Sanhita?

> Compare IPC Section 302 with BNS Section 101.

Step 4: Configure transport (optional)

By default, the server uses stdio transport (for local use with Claude Desktop, opencode, etc.).

For remote/shared deployments, use Streamable HTTP:

# Set transport to Streamable HTTP
export THEMIS_MCP_TRANSPORT=streamable-http
export THEMIS_MCP_HOST=0.0.0.0
export THEMIS_MCP_PORT=8000

# Start the server
themis-mcp

Environment Variable	Default	Description
THEMIS_MCP_TRANSPORT	stdio	stdio or streamable-http
THEMIS_MCP_HOST	0.0.0.0	Host to bind to (HTTP mode)
THEMIS_MCP_PORT	8000	Port to listen on (HTTP mode)
THEMIS_MCP_TOOLS	ask,lookup	Comma-separated list of tools to enable

---

Tools

themis_ask

Answer a question about Indian statutory law (BNS, IPC, BNSS, BSA, RTI, CPA).

Parameter	Type	Default	Description
question	string	required	Legal question about Indian law
temperature	float	0.7	Generation temperature (0.0-1.0). Lower = more deterministic
max_tokens	int	512	Maximum tokens to generate

Example response:

{
  "text": "Section 103 of the Bharatiya Nyaya Sanhita, 2023 defines murder as..."
}

themis_lookup

Retrieve the exact text of a legal section from anchor tables. Fast, deterministic, no LLM inference.

Parameter	Type	Description
act	string	One of: bns, bnss, bsa, ipc, rti_2005, consumer_protection_2019
section	string	Section number (e.g. "302", "63")

themis_map_section

EXPERIMENTAL: Map an IPC section to its BNS equivalent (or vice versa).

⚠️ Warning: These mappings are AI-generated and partially verified. Of 207 entries, 27 have been verified against official sources (NCRB, LawSikho). 180 remain unverified. Always cross-check with official sources (Ministry of Law and Justice, NCRB).

Parameter	Type	Description
source_act	string	"ipc" or "bns"
section	string	Section number (e.g. "302", "103")
target_act	string	"bns" or "ipc" (optional, auto-detected)

Example:

> Map IPC Section 302 to BNS

IPC Section 302 corresponds to BNS Section 103.

WARNING: These mappings are UNVERIFIED and AI-generated. Do NOT treat as authoritative legal references.

---

Health Check

When running in Streamable HTTP mode, a /health endpoint is available:

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "service": "themis-mcp",
  "model_loaded": true
}

Returns 503 if the model is still loading.

---

Resources

URI	Description
themis://disclaimer	Legal disclaimer (appended to all tool responses)
themis://acts	List of supported acts with section counts
themis://laws/pdf	Official PDF links for all supported statutes
themis://laws/{act}/pdf	Official PDF link for a specific statute

---

Prompts

Pre-built legal query templates for common tasks:

Prompt	Description	Args
compare_ipc_bns	Compare IPC section with BNS equivalent	section (e.g. "302")
explain_section	Explain a section in plain language	act, section
punishment_for	Find punishment for an offense	act, offense
rti_rights	RTI citizen rights query	section (default: "6")
consumer_complaint	Consumer complaint filing guide	—
section_summary	Quick section lookup with significance	act, section

Usage in MCP clients:

Use the themis prompt "compare_ipc_bns" with section "302"

---

Caching

Deterministic queries (temperature ≤ 0.1) are cached for 5 minutes (128 entries max).

Cache stats are included in the /health endpoint response:

{
  "cache": {
    "size": 12,
    "max_size": 128,
    "hits": 45,
    "misses": 23,
    "hit_rate": "66.2%"
  }
}

---

Sampling

When the client supports MCP sampling, the server can request AI-assisted clarification for ambiguous questions. This is opt-in and gracefully degrades if the client doesn't support it.

---

IPC ↔ BNS Mapper

Cross-reference sections between old (IPC) and new (BNS) criminal laws:

# Via tool
> Map IPC 302 to BNS

IPC Section 302 corresponds to BNS Section 103.

WARNING: These mappings are UNVERIFIED and AI-generated. Do NOT treat as authoritative legal references.

# Reverse mapping
> Map BNS Section 103 to IPC

BNS Section 103 corresponds to IPC Section 302.

207 mappings included. 27 verified against NCRB and LawSikho official sources. 180 unverified — always cross-check with official sources before relying on these in legal proceedings.

---

Legal Citations

Format citations in multiple styles:

from themis_mcp.citation import format_citation, format_inline_citation, format_footnote

format_citation("bns", "103")
# 'Section 103, The Bharatiya Nyaya Sanhita, 2023'

format_citation("ipc", "302", short=True)
# 'IPC s. 302'

format_inline_citation("bns", "103")
# '(BNS, s. 103)'

format_footnote("bns", "103")
# 'Bharatiya Nyaya Sanhita, 2023, s. 103.'

---

Prometheus Metrics

When running in HTTP mode, metrics are available at /metrics:

curl http://localhost:8000/metrics

Available metrics:

• themis_tool_calls_total — Total tool calls (labels: tool)
• themis_tool_errors_total — Tool errors (labels: tool, error)
• themis_tool_duration_seconds — Tool call duration histogram
• themis_cache_hits_total — Cache hits
• themis_uptime_seconds — Server uptime

---

Session Management

HTTP mode tracks active sessions with automatic timeout (1 hour default).

Session stats are included in /health:

{
  "sessions": {
    "active_sessions": 3,
    "timeout_seconds": 3600
  }
}

---

Dynamic Tool Loading

Control which tools are exposed to the MCP client via environment variable:

# Only expose the ask tool (no lookup)
export THEMIS_MCP_TOOLS=ask

# Only expose the lookup tool (no LLM inference)
export THEMIS_MCP_TOOLS=lookup

# Both tools (default)
export THEMIS_MCP_TOOLS=ask,lookup

---

Rate Limiting

The themis_ask tool is rate-limited to prevent abuse:

• Limit: 30 calls per minute
• Response: Error (RATE_LIMITED): Rate limit exceeded. Try again in X seconds.

Configure via the RateLimitConfig in ratelimit.py if needed.

---

Error Handling

Errors are classified into three categories:

Class	Meaning	LLM Action
CLIENT_ERROR	Bad input, missing params	Self-correct the request
SERVER_ERROR	Internal failure (GPU, model)	Abort and notify user
EXTERNAL_ERROR	Network, download failure	Retry with backoff

Example error response:

Error (SERVER_ERROR): Insufficient GPU memory
Details: THEMIS requires ~13GB VRAM. Close other GPU applications.

---

OpenTelemetry Tracing

Optional tracing for production monitoring. Install with:

pip install "themis-mcp[otel]"

Traces are emitted for every tool call with:

• mcp.tool.name — tool being called
• mcp.tool.question — input (truncated to 100 chars)
• Latency and error status

---

Usage Examples

Basic legal question

User: What is the punishment for robbery under BNS?

THEMIS: Section 309 of the Bharatiya Nyaya Sanhita, 2023 defines robbery 
as whoever commits robbery shall be punished with rigorous imprisonment 
for a term which may extend to ten years, and shall also be liable to fine.

---
This is not legal advice. THEMIS provides orientation on Indian statutory law. 
Consult a qualified lawyer for authoritative guidance.

Direct section lookup

User: Look up IPC Section 302

THEMIS: Section 302 — IPC

302. Punishment for murder
Whoever commits murder shall be punished with death, or imprisonment 
for life, and shall also be liable to fine.
---
This is not legal advice. THEMIS provides orientation on Indian statutory law.

IPC to BNS mapping

User: Map IPC Section 302 to BNS

THEMIS: IPC Section 302 corresponds to BNS Section 103.

WARNING: These mappings are UNVERIFIED and AI-generated. Do NOT treat as authoritative legal references.

Comparing IPC and BNS sections

User: Use the themis prompt "compare_ipc_bns" with section "302"

THEMIS: IPC Section 302 (Murder) corresponds to BNS Section 103.
BNS 103 adds mob lynching as an aggravated form with enhanced punishment.

Finding punishment for an offense

User: Use the themis prompt "punishment_for" with act "BNS" and offense "theft"

THEMIS: Section 303 of the Bharatiya Nyaya Sanhita, 2023 defines theft.
Whoever commits theft shall be punished with imprisonment of either 
description for a term which may extend to three years, or with fine, 
or with both.

Law PDF resources

User: Get the PDF link for BNS

THEMIS: {
  "title": "Bharatiya Nyaya Sanhita, 2023",
  "pdf_url": "https://www.indiacode.nic.in/bitstream/...",
  "date_enacted": "2023-12-25",
  "effective_date": "2024-07-01"
}

---

Troubleshooting

"No GPU available or CUDA not configured"

THEMIS requires a CUDA-capable GPU with ~13GB VRAM.

1. Verify CUDA is installed: nvidia-smi
2. Install CUDA: https://developer.nvidia.com/cuda-downloads
3. Ensure PyTorch sees CUDA: python -c "import torch; print(torch.cuda.is_available())"

"Insufficient GPU memory"

Close other GPU-intensive applications (browser tabs with hardware acceleration, other ML models, etc.).

"Failed to download model weights"

Check your internet connection. The model weights (~13GB) are downloaded from HuggingFace on first run.

"THEMIS model not loaded"

The server may still be starting up. Wait a few seconds and try again. If the error persists, check the server logs.

Model loads slowly on first run

First run downloads ~13GB of model weights from HuggingFace. Subsequent runs use the cached weights.

---

Relationship to THEMIS

	themis-mcp	themis-llm
Interface	MCP tools	Python SDK + CLI
Use case	AI assistants (Claude, Cursor)	Scripts, notebooks, apps
Model loading	Local (GPU required)	Local (GPU required)

---

Disclaimer

THEMIS provides orientation on Indian statutory law. It is not legal advice. Consult a qualified lawyer for authoritative guidance.

---

License

MIT

---

Citation

@misc{themis-mcp2026,
  author = {Daniel Deshmukh},
  title = {themis-mcp: MCP Server for Indian Statutory Law Q\&A},
  year = {2026},
  url = {https://github.com/DanielDeshmukh/themis-mcp}
}

---

THEMIS — Greek goddess of law, justice, and order. Because justice should not require a law degree to understand.