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