esg-mcp-servers

ESG MCP Servers

<!-- mcp-name: io.github.freminder/esg-mcp-servers -->

Open-source Model Context Protocol servers for ESG (Environmental, Social, and Governance) data extraction, analysis, and regulation management.

31 tools across 6 servers — install once, run only what you need.

Author: Ioannis Michos (johnmichos.tf@gmail.com)

Quick Start

pip install esg-mcp-servers

Prerequisites

| Service | Required for | |---------|-------------| | PostgreSQL 16 + pgvector | Vector storage, metrics, regulations | | MongoDB 7 | PDF binary storage (GridFS) | | Anthropic API key | RAG queries, metric extraction |

Spin up local databases with Docker:

docker compose up -d

Run the database migration:

esg-mcp-migrate

Environment Variables

Copy .env.example and fill in your values:

cp .env.example .env

Key variables:

| Variable | Default | Description | |----------|---------|-------------| | POSTGRES_DSN | postgresql://esg:esg@localhost/esg_platform | PostgreSQL connection string | | MONGODB_URI | mongodb://localhost:27017 | MongoDB connection string | | ANTHROPIC_API_KEY | — | Required for RAG and LLM extraction | | EMBEDDING_MODEL | Snowflake/snowflake-arctic-embed-l-v2.0 | Sentence-transformer model | | EMBEDDING_DIMENSIONS | 1024 | Embedding vector size |

Servers & Tools

esg-metrics-extractor (11 tools)

ESRS-aligned KPI extraction for emissions, energy, water, waste, social, and governance domains.

| Tool | Description | |------|-------------| | extract_emissions_data | GHG Scope 1, 2, 3 extraction | | extract_energy_data | Energy consumption & renewables (ESRS E2) | | extract_water_data | Water withdrawal, discharge, consumption (ESRS E3) | | extract_waste_data | Waste generation, recycling, landfill (ESRS E5) | | extract_social_data | Workforce, diversity, H&S (ESRS S1) | | extract_governance_data | Board composition & governance (ESRS G1) | | answer_esg_query | Free-text RAG Q&A over documents | | keyword_similarity_search | Semantic keyword search in documents | | detect_query_domain | Classify query into ESG domain | | detect_emissions_query_type | Detect emissions scope/year from query | | batch_extract_metrics | Extract all KPIs and persist to DB |

esg-pdf-processor (5 tools)

PDF validation, text/table extraction, and embedding generation.

| Tool | Description | |------|-------------| | verify_esg_report | RandomForest ESG report classifier | | extract_text_chunks | Extract and chunk PDF text | | extract_tables | Table extraction with OCR fallback | | generate_embeddings | Batch embedding generation | | process_pdf_full_pipeline | End-to-end: extract, embed, store |

esg-vector-store (5 tools)

pgvector CRUD operations for document chunks and query cache.

| Tool | Description | |------|-------------| | upsert_document_chunks | Insert/update chunks with embeddings | | similarity_search | Cosine similarity search | | get_cached_query_response | Retrieve cached LLM responses | | cache_query_response | Store LLM response in cache | | list_documents | List indexed documents |

esg-regulations (5 tools)

EU ESG regulation download, ingestion, and semantic search.

| Tool | Description | |------|-------------| | download_regulation | Download regulation PDF from EUR-Lex | | download_all_regulations | Batch download all configured regulations | | ingest_regulation | Extract, parse articles, embed, store | | search_regulation_text | Semantic search across regulation articles | | list_regulations | List ingested regulations |

esg-scraper (5 tools)

ESG report discovery and download from the web.

| Tool | Description | |------|-------------| | search_esg_reports | Multi-engine search for ESG PDFs | | crawl_company_website | Deep-crawl website for PDF links | | download_pdf | Download PDF and store in GridFS | | get_scraping_status | Check scrape job status | | cancel_scraping_job | Cancel running scrape job |

esg-mcp-all (31 tools)

All tools from all servers in a single process.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "esg-metrics": {
      "command": "esg-metrics-extractor"
    },
    "esg-pdf": {
      "command": "esg-pdf-processor"
    },
    "esg-vectors": {
      "command": "esg-vector-store"
    },
    "esg-regulations": {
      "command": "esg-regulations"
    },
    "esg-scraper": {
      "command": "esg-scraper"
    }
  }
}

Or use the combined server for all tools:

{
  "mcpServers": {
    "esg": {
      "command": "esg-mcp-all"
    }
  }
}

Optional: Scraper Dependencies

The scraper server requires Selenium for JavaScript-heavy sites:

pip install esg-mcp-servers[scraper]

Development

git clone https://github.com/freminder/esg-mcp-servers.git
cd esg-mcp-servers
pip install -e ".[scraper,dev]"
docker compose up -d
esg-mcp-migrate

License

MIT — see LICENSE.