MCP 服务器

Jana MCP Server

Provides natural language access to environmental data including air quality measurements, greenhouse gas emissions, and facility records. It enables users to perform geographic searches, trend analysis, and proximity-based queries using data from sources like OpenAQ and Climate TRACE.

README

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.