Skip to main content
Glama
rithik-cmyk

ecourts-mcp-server

by rithik-cmyk
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript

ecourts-mcp-server v1.2.0

An MCP (Model Context Protocol) server that connects LLMs to the EcourtsIndia Partner API v1.3, enabling AI agents to search Indian court cases, retrieve orders, read cause lists, and access AI-generated summaries.

Tools (9 total)

Tool

Description

Billing

ecourts_get_case

Full case detail by CNR — parties, orders, IAs, notices, documents, hearings, FIR, linked cases, file AI status, case AI analysis

Per-request

ecourts_lookup_case

Workflow tool — find a case by human-readable number (e.g. "CS(OS) 123/2024") instead of CNR, returns full details

Per-request

ecourts_search_cases

Rich search with 30+ filter params, year filters, date ranges, faceted aggregations

Per-request

ecourts_get_order

Download order PDF with metadata (certified true copies)

Per-request

ecourts_get_order_ai

Extracted order text + pre-computed AI analysis (summary, outcome, key points)

Per-request

ecourts_get_court_structure

Browse state → district → complex → court hierarchy

Free

ecourts_search_causelist

Search cause list entries across all courts

₹1/request

ecourts_get_causelist_dates

Available cause list dates

Free

ecourts_refresh_case

Queue a fresh scrape of case data

Per-request

Related MCP server: Law7 MCP

Quick Start

npm install
npm run build
export ECOURTS_API_TOKEN="eci_live_your_token_here"
npm start

Deployment

Docker

# Build
docker build -t ecourts-mcp-server .

# Run
docker run -d \
  -e ECOURTS_API_TOKEN=eci_live_your_token_here \
  -p 3000:3000 \
  ecourts-mcp-server

# Health check
curl http://localhost:3000/health

Docker Compose

# Set your token
export ECOURTS_API_TOKEN=eci_live_your_token_here

# Start
docker compose up -d

# Verify
curl http://localhost:3000/health

Cloud Deployment

The Docker image works with any container platform:

  • AWS ECS / Fargate — Use the health check endpoint at /health

  • Google Cloud Run — Set PORT=8080 (Cloud Run default), server auto-adapts

  • Azure Container Apps — Standard HTTP container deployment

  • Railway / Render / Fly.io — Push the Dockerfile, set ECOURTS_API_TOKEN in secrets

The image runs as a non-root user, includes a HEALTHCHECK, and defaults to HTTP transport on port 3000.

Claude Desktop (stdio)

{
  "mcpServers": {
    "ecourts": {
      "command": "node",
      "args": ["/path/to/ecourts-mcp-server/dist/index.js"],
      "env": {
        "ECOURTS_API_TOKEN": "eci_live_your_token_here"
      }
    }
  }
}

Claude Code (stdio)

claude mcp add ecourts -- node /path/to/ecourts-mcp-server/dist/index.js

Running Tests

npm test                # 110 unit tests via vitest
npm run test:integration  # 24 integration tests (requires ECOURTS_API_TOKEN)
npm run test:all          # both

Tests cover: query parameter serialization, all formatting functions, facet rendering, all 14 API error code branches, schema boundary validation, safeHandler wrapper, truncation, date validation, and typed fields. Integration tests cover court structure hierarchy, case search with filters/sort/years, case detail, order metadata, cause list search by date, case refresh, and error scenarios.

CI/CD

The .github/workflows/ci.yml pipeline:

  1. Build & test on Node 20 and 22 (on push/PR to main)

  2. Docker build + health check on push to main

Architecture

src/
├── index.ts              # Entry point, transport (stdio/HTTP), health endpoint
├── constants.ts          # Base URLs, character limits
├── types.ts              # Full TypeScript interfaces for all API responses
├── schemas/index.ts      # Zod input validation with date regex enforcement
├── services/
│   ├── api-client.ts     # HTTP client, binary download, repeated-key array serializer, error handling
│   └── formatting.ts     # Markdown formatters for case, search, causelist, order
└── tools/index.ts        # 9 tool registrations with MCP annotations

Environment Variables

Variable

Required

Description

ECOURTS_API_TOKEN

Yes

EcourtsIndia Partner API bearer token

TRANSPORT

No

stdio (default) or http

PORT

No

HTTP port (default 3000, only for http transport)

Changelog

v1.2.0 (current)

Code Quality:

  • Eliminated all unsafe type casts — linkCases, subordinateCourt, and firDetails are now proper typed fields on CourtCaseData

  • CauseListEntry expanded with petitionerAdvocates, respondentAdvocates, internalCaseNo, dateCreated, dateModified

  • Proper AvailableDatesResponse and CaseFileSummary types replace inline anonymous types

  • All date parameters validated with YYYY-MM-DD regex at schema level

New Features:

  • ecourts_lookup_case — workflow tool that finds cases by human-readable number (e.g. "CS(OS) 123/2024") instead of CNR

  • Order file status in case detail — ecourts_get_case now shows which orders have AI analysis available with summary previews

  • Health check endpoint — GET /health for load balancers and container orchestrators

  • Error-safe HTTP transport — Express handler now catches errors instead of hanging

  • ecourts_get_order PDF download — returns order PDF as embedded resource with metadata (filename, file size) extracted from HTTP headers

Deployment:

  • Multi-stage Dockerfile (22MB Alpine image, non-root user, HEALTHCHECK)

  • docker-compose.yml with health check and token validation

  • GitHub Actions CI (Node 20/22 matrix, Docker build verification)

  • Test suite expanded to 110 unit tests + 24 integration tests

v1.1.0

  • Fixed array parameter serialization (courtCodes, caseTypes, etc.)

  • Added isError flag on MCP error responses

  • Complete error code handling (11 API error codes)

  • 15+ new search parameters (year filters, date ranges, categories, bench types)

  • Facet counts in search output

  • Comprehensive case detail formatting (all sections)

v1.0.0

  • Initial release with 8 tools covering all EcourtsIndia Partner API endpoints

Available Tools

3 tools
ecourts_get_caseGet Case DetailsA
Read-onlyIdempotent

Retrieve comprehensive details for an Indian court case by CNR (Case Number Record).

Returns: case status, parties (petitioners/respondents), advocates, judges, hearing history, listing dates, judgment orders, interim orders, interlocutory applications, notices, filed documents, tagged/connected matters, linked cases, earlier court details, FIR details (criminal), subordinate court, and AI case analysis.

Args:

  • cnr (string): Case Number Record, e.g. "DLHC010001232024"

Use this tool first to discover available order filenames (judgmentOrders[].orderUrl, interimOrders[].orderUrl) before calling ecourts_get_order or ecourts_get_order_ai.

ParametersJSON Schema
NameRequiredDescriptionDefault
cnrYesCase Number Record, e.g. DLHC010001232024

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds value by detailing the comprehensive return fields (case status, parties, orders, etc.) and explaining how to discover order filenames, which goes beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences that quickly convey the main purpose, return content, and usage guidance. No extraneous information is present, earning full marks.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of Indian court cases and the absence of an output schema, the description provides a thorough list of return fields and valuable guidance on using the tool in conjunction with sibling tools. This fully compensates for any missing structured information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a 100% description coverage for the single parameter 'cnr', including an example. The description repeats the example but adds no new semantic detail beyond what the schema offers, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Retrieve comprehensive details' and the resource 'Indian court case by CNR'. It differentiates from siblings by explicitly noting that this tool should be used first to discover order filenames before calling ecourts_get_order or ecourts_get_order_ai.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance on when to use this tool: use it first to discover order filenames. However, it does not explicitly state when not to use it or mention alternatives beyond the sibling tools, leaving some room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ecourts_get_causelist_datesGet Cause List Available DatesA
Read-onlyIdempotent

Get dates for which cause list data is available, filtered by location.

At least one parameter is required: state, district_code, court_complex_code, or court_no.

Free endpoint (no credit charge, authentication required). Use the returned dates with ecourts_search_causelist to avoid empty searches.

ParametersJSON Schema
NameRequiredDescriptionDefault
stateNoState code, e.g. DL
court_noNoCourt room number
district_codeNoDistrict code
court_complex_codeNoCourt complex code

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds behavioral traits beyond annotations: 'Free endpoint (no credit charge, authentication required)' and 'At least one parameter is required' (a constraint not fully captured in schema). Annotations already declare readOnly, idempotent, and non-destructive, so the description complements without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no wasted words. Purpose stated first, then usage constraints, then practical guidance. Extremely efficient for the information conveyed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description appropriately explains the return value (dates) and its intended use. It also mentions authentication and free credit usage. It adequately covers the necessary context for a simple lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions like 'State code, e.g. DL'. The description adds meaning by explaining that at least one parameter is required and that the output dates are intended for use with ecourts_search_causelist, enhancing the understanding of parameter purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb-resource combination: 'Get dates for which cause list data is available'. The description explicitly states filtering by location, and the tool's purpose is distinct from sibling tools (ecourts_search_cases, ecourts_get_case), which deal with case data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit context: 'Use the returned dates with ecourts_search_causelist to avoid empty searches.' Also states the prerequisite that at least one parameter is required. However, it does not contrast usage with siblings or specify when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ecourts_search_casesSearch Court CasesA
Read-onlyIdempotent

Search for Indian court cases with text queries, filters, date ranges, year filters, and faceted aggregations.

Text search args (all optional): query, advocates, judges, petitioners, respondents, litigants

Filter args (arrays): court_codes, case_types, case_statuses, judicial_sections, case_categories, bench_types

Year filters (integer arrays): filing_years, registration_years, first_hearing_years, next_hearing_years, decision_years

Date ranges (YYYY-MM-DD): filing_date_from/to, registration_date_from/to, first_hearing_date_from/to, next_hearing_date_from/to, decision_date_from/to

Controls: include_facet_counts (bool), sort_by, sort_order, page, page_size (max 100)

Returns: matching cases with CNR, parties, dates, facet counts. Supply at least one search term or filter.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoPage number (1-based)
queryNoGeneral full-text search across all fields
judgesNoSearch by judge name
sort_byNoField to sort by
advocatesNoSearch by advocate name (both petitioner and respondent advocates)
litigantsNoSearch petitioners AND respondents simultaneously
page_sizeNoResults per page (max 100)
case_typesNoFilter by case types: CIVIL, CRIMINAL, WRIT, APPEAL, REVISION, EXECUTION, ARBITRATION, MATRIMONIAL, MOTOR_ACCIDENT, LABOR
sort_orderNoSort direction
bench_typesNoFilter by bench type, e.g. ['SINGLE','DIVISION']
court_codesNoFilter by court codes, e.g. ['DLHC01','HCBM01']. Use ecourts_get_court_structure or the enum reference.
petitionersNoSearch by petitioner name
respondentsNoSearch by respondent name
filing_yearsNoFilter by filing year(s), e.g. [2024, 2023]
case_statusesNoFilter by statuses: PENDING, DISPOSED, TRANSFERRED, WITHDRAWN, UNKNOWN
decision_yearsNoFilter by decision year(s)
filing_date_toNoFiling date range end (YYYY-MM-DD)
case_categoriesNoFilter by case categories, e.g. ['COMMERCIAL']
decision_date_toNoDecision date range end (YYYY-MM-DD)
filing_date_fromNoFiling date range start (YYYY-MM-DD)
judicial_sectionsNoFilter by judicial sections: CIV, CRIM, WRIT, REV, APP, MISC, PIL, BAIL, URG, ADM
decision_date_fromNoDecision date range start (YYYY-MM-DD)
next_hearing_yearsNoFilter by next hearing year(s)
registration_yearsNoFilter by registration year(s)
first_hearing_yearsNoFilter by first hearing year(s)
include_facet_countsNoInclude facet (aggregation) counts in response. Default true.
next_hearing_date_toNoNext hearing date range end (YYYY-MM-DD)
registration_date_toNoRegistration date range end (YYYY-MM-DD)
first_hearing_date_toNoFirst hearing date range end (YYYY-MM-DD)
next_hearing_date_fromNoNext hearing date range start (YYYY-MM-DD)
registration_date_fromNoRegistration date range start (YYYY-MM-DD)
first_hearing_date_fromNoFirst hearing date range start (YYYY-MM-DD)

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds details on parameter constraints (max page size, date format), facet counts, and return fields, complementing the safety profile without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with bullet points, clear category headers, and no extraneous text. It efficiently conveys all necessary information for a complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (32 parameters, no output schema), the description covers all parameter groups, constraints, and typical usage. It lacks explicit pagination or error details but is sufficient for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% description coverage. The description groups parameters into logical categories (text, filters, years, dates, controls), adding semantic structure that aids understanding beyond individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for Indian court cases with various criteria, listing supported query types and return fields. It distinguishes from sibling tools (causelist dates, specific case retrieval) by focusing on search and filtering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description requires at least one search term or filter, and categorizes parameters into text, filters, dates, etc. It does not explicitly compare to alternatives but the purpose is clear relative to sibling tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv1.2.0
    • First observedecourts_get_case
    • First observedecourts_get_causelist_dates
    • First observedecourts_search_cases
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: searching cases with filters, retrieving cause list availability dates, and getting detailed case info by CNR. No overlap in functionality.

Naming Consistency5/5

All tools follow a consistent 'ecourts_<verb>_<noun>' pattern (search_cases, get_causelist_dates, get_case), making them predictable and easy to distinguish.

Tool Count2/5

Only 3 tools are provided, which is too few for the apparent scope of an Indian court case retrieval system. The descriptions reference missing tools like ecourts_search_causelist and ecourts_get_order, indicating the set is incomplete.

Completeness2/5

The tool surface has significant gaps: there is no tool to actually retrieve a cause list or obtain court orders, even though the get_case tool returns order URLs. Users cannot complete full workflows as described.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers