Jana MCP Server

MCP Server for Jana Environmental Data Platform

A Model Context Protocol (MCP) server that provides natural language access to environmental data including air quality measurements, greenhouse gas emissions, and facility data.

Features

Air Quality Data — Query PM2.5, PM10, O3, NO2, SO2, CO measurements from OpenAQ
Emissions Data — Access facility-level and national GHG emissions from Climate TRACE and EDGAR
Geographic Search — Find environmental data by bounding box, point + radius, or country
Trend Analysis — Analyze temporal patterns in environmental data
System Health — Monitor platform status and data availability

Architecture

This MCP server runs as a hosted HTTP service using FastAPI with SSE (Server-Sent Events) transport. It communicates with the Jana backend API for data access.

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│  MCP Client         │     │  Jana MCP Server    │     │  Jana Backend       │
│  (Cursor/Claude)    │────▶│  (FastAPI + SSE)    │────▶│  (Django + DRF)     │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘

Quick Start

Prerequisites

Docker and Docker Compose
Running Jana backend (see Jana repository)

1. Configure Environment

Copy the example environment file and configure:

cp dotenv.example .env

Edit .env with your Jana backend credentials:

JANA_BACKEND_URL=http://host.docker.internal:8000
JANA_USERNAME=your_username
JANA_PASSWORD=your_password

2. Start the Server

Standalone mode (Jana backend running on host):

docker-compose up --build

With Jana stack (same Docker network):

# First, start Jana backend
cd ../Jana
docker-compose up -d

# Then start MCP server with override
cd ../jana-mcp-server
docker-compose -f docker-compose.yml -f docker-compose.override.yml up --build

The MCP server will be available at http://localhost:8080.

3. Configure Your MCP Client

Add to your Cursor or Claude Code MCP configuration:

{
  "mcpServers": {
    "jana": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Available Tools

Tool	Description	Priority
`get_air_quality`	Query air quality measurements	P0
`get_emissions`	Query GHG emissions data	P0
`find_nearby`	Proximity-based search	P0
`get_trends`	Temporal trend analysis	P1
`get_data_summary`	Platform data summary	P1
`get_system_health`	Service status check	P2

Development

Docker Development (Recommended)

The Docker setup includes live code reload - code changes are immediately reflected without rebuilding the container.

# Start with live reload (standalone mode)
docker-compose up

# Or with Jana stack
docker-compose -f docker-compose.yml -f docker-compose.override.yml up

How it works:

Volume mount: ./src:/app/src maps local code into container
Uvicorn --reload flag watches for changes and auto-restarts
No container rebuild needed for Python code changes

When to rebuild:

Changes to pyproject.toml (new dependencies)
Changes to Dockerfile
System-level changes

docker-compose up --build

Local Development (without Docker)

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

# Run server with auto-reload
uvicorn jana_mcp.app:app --reload --port 8080

Running Tests

pytest

# With coverage
pytest --cov=jana_mcp --cov-report=html

Code Quality

# Linting
ruff check .

# Type checking
mypy src/

Production Deployment

For production, use the production compose file (no live reload, optimized):

docker-compose -f docker-compose.prod.yml up -d

API Endpoints

Endpoint	Method	Description
`/`	GET	Server information
`/health`	GET	Health check
`/sse`	GET	SSE connection for MCP
`/messages`	POST	MCP message handling

Configuration

Variable	Description	Default
`JANA_BACKEND_URL`	Jana backend URL	`http://web:8000`
`JANA_USERNAME`	Auth username	(required)
`JANA_PASSWORD`	Auth password	(required)
`JANA_TOKEN`	Pre-configured token	(optional)
`MCP_SERVER_PORT`	Server port	`8080`
`LOG_LEVEL`	Logging level	`INFO`

Known Limitations

get_data_summary may timeout — The backend summary endpoint aggregates data across 300M+ records which can exceed timeout limits. The tool gracefully returns partial results with available source information when this occurs.

Documentation

User Manual — How to connect and use the MCP server
Architecture
Requirements
Architecture Decision Records

License

MIT