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.

Verify CUDA is installed: nvidia-smi
Install CUDA: https://developer.nvidia.com/cuda-downloads
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.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src/themis_mcp		src/themis_mcp
tests		tests
.gitignore		.gitignore
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

themis-mcp

What is this?

Requirements

Quick Start

Step 1: Install

Step 2: Configure your MCP client

Step 3: Use it

Step 4: Configure transport (optional)

Tools

themis_ask

themis_lookup

themis_map_section

Health Check

Resources

Prompts

Caching

Sampling

IPC ↔ BNS Mapper

Legal Citations

Prometheus Metrics

Session Management

Dynamic Tool Loading

Rate Limiting

Error Handling

OpenTelemetry Tracing

Usage Examples

Basic legal question

Direct section lookup

IPC to BNS mapping

Comparing IPC and BNS sections

Finding punishment for an offense

Law PDF resources

Troubleshooting

"No GPU available or CUDA not configured"

"Insufficient GPU memory"

"Failed to download model weights"

"THEMIS model not loaded"

Model loads slowly on first run

Relationship to THEMIS

Disclaimer

License

Citation

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`themis_ask`

`themis_lookup`

`themis_map_section`