Esg MCP Servers README

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

Terminal

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:

Terminal

docker compose up -d

Run the database migration:

bash

esg-mcp-migrate

Environment Variables

Copy .env.example and fill in your values:

bash

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:

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:

config.json

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

Optional: Scraper Dependencies

The scraper server requires Selenium for JavaScript-heavy sites:

Terminal

pip install esg-mcp-servers[scraper]

Development

bash

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.