IndianRailwaysMCP

graph TD
    Client["🖥️ MCP Client<br/>(Claude Desktop / Cursor / Continue.dev)"] -->|MCP Protocol · stdio| Server

    subgraph Server["🚂 Indian Railways MCP Server"]
        direction TB
        SL["🛠️ Server Layer<br/>Tool registration (10 tools)<br/>Pydantic input validation"]
        CL["🌐 Client Layer<br/>httpx session mgmt<br/>tenacity retry logic<br/>TTL response cache"]
        PL["🔎 Parser Layer<br/>BeautifulSoup HTML parsing<br/>Pydantic JSON parsing<br/>Regex extraction"]
        SL --> CL --> PL
    end

    PL -->|HTTP/HTTPS| ERail[("🗄️ ERail.in<br/>Schedules · Live status<br/>PNR · Seats · Fares")]
    PL -->|HTTP/HTTPS| IRInfo[("🗄️ IndianRailways.info<br/>Coach position<br/>Platform locator")]

git clone https://github.com/Shadhai/Railway_mcp.git
cd Railway_mcp

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate      # Linux/Mac
# .venv\Scripts\activate       # Windows

# Install dependencies
pip install mcp httpx beautifulsoup4 pydantic tenacity

# Run directly
python -m src.indian_railways_mcp.server

# Or install as a package and run the entry point
pip install -e .
indian-railways-mcp

✅ Available tools: 10
  - search_stations: Search Indian Railways stations by name or code...
  - search_trains: Search Indian Railways trains by number or name...
  - get_train_schedule: Get complete train schedule with all stations...
  ...

# ── Runtime ─────────────────────────────────────────────
PYTHONPATH=/path/to/Railway_mcp/src

# <!-- VERIFY: add PORT/NODE_ENV-style vars here only if you front this
#      server with a custom HTTP/SSE transport wrapper. Stdio transport
#      (the default) needs nothing beyond PYTHONPATH. -->

from indian_railways_mcp.client import IndianRailwaysClient

client = IndianRailwaysClient()

trains = client.get_trains_between("NDLS", "BCT")
train = trains['trains'][0]

seats = client.check_seat_availability(
    train['train_number'], "NDLS", "BCT", "20-Jul-2026"
)

if any(c['status'] == 'AVAILABLE' for c in seats['classes']):
    fare = client.get_fare(train['train_number'], "NDLS", "BCT")
    print(f"Fare: ₹{fare['classes'][0]['total_fare']}")

schedule = client.get_train_schedule(train['train_number'])
print(f"Travel time: {schedule['travel_time']} hours")

status = client.get_live_status("04815")

if status['status'] == 'RUNNING':
    print(f"{status['train_name']} last seen at {status['last_station']}, "
          f"delayed {status['delay_minutes']} min")

pnr = client.check_pnr("4553137968")

for p in pnr['passengers']:
    print(f"Passenger {p['serial']}: {p['current_status']} | "
          f"Coach {p['coach']} | Berth {p['berth']} ({p['berth_type']})")

Railway_mcp/
├── 📄 README.md                     # Main documentation
├── 📄 pyproject.toml                # Package configuration
├── 📄 LICENSE                       # MIT License
├── 📄 .gitignore                    # Git ignore rules
├── 📁 docs/
│   ├── API_REFERENCE.md             # Complete tool/API documentation
│   ├── ARCHITECTURE.md              # System architecture
│   └── EXAMPLES.md                  # Usage examples
├── 📁 src/
│   └── 📁 indian_railways_mcp/
│       ├── __init__.py              # Package init
│       ├── server.py                # MCP server (10 tools)
│       ├── client.py                # HTTP client (all endpoints)
│       ├── parsers.py               # HTML/JSON parsers
│       ├── models.py                # Pydantic data models
│       └── utils.py                 # Caching + retry utilities
└── 📁 tests/
    ├── test_client.py               # Client tests
    └── test_parsers.py              # Parser tests

{
  "mcpServers": {
    "indian-railways": {
      "command": "python",
      "args": ["-m", "src.indian_railways_mcp.server"],
      "cwd": "/path/to/Railway_mcp",
      "env": { "PYTHONPATH": "/path/to/Railway_mcp/src" }
    }
  }
}

{
  "mcpServers": {
    "indian-railways": {
      "command": "python",
      "args": ["-m", "src.indian_railways_mcp.server"],
      "cwd": "/path/to/Railway_mcp"
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "python",
          "args": ["-m", "src.indian_railways_mcp.server"],
          "cwd": "/path/to/Railway_mcp"
        }
      }
    ]
  }
}

npx @modelcontextprotocol/inspector python -m src.indian_railways_mcp.server

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY src/ ./src/

ENV PYTHONPATH=/app

CMD ["python", "-m", "src.indian_railways_mcp.server"]

# Build
docker build -t indian-railways-mcp .

# Run (stdio requires interactive mode)
docker run -i indian-railways-mcp

[Unit]
Description=Indian Railways MCP Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/indian-railways-mcp
Environment=PYTHONPATH=/opt/indian-railways-mcp/src
ExecStart=/usr/bin/python3 -m src.indian_railways_mcp.server
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable indian-railways-mcp
sudo systemctl start indian-railways-mcp
sudo systemctl status indian-railways-mcp

# Install test dependencies
pip install pytest pytest-cov pytest-mock pytest-asyncio

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src/indian_railways_mcp --cov-report=html

# Run a specific file / class / test
pytest tests/test_client.py -v
pytest tests/test_client.py::TestPNRStatus -v
pytest tests/test_client.py::TestPNRStatus::test_check_pnr_success -v

# 1. Fork the repository
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/Railway_mcp.git
cd Railway_mcp

# 3. Create a feature branch
git checkout -b feature/your-feature-name

# 4. Make your changes and add tests
pytest tests/ -v

# 5. Commit and push
git commit -m "Add: your feature description"
git push origin feature/your-feature-name

# 6. Open a Pull Request against main