ie_mcp

Using the ie_mcp server makes coding with Industrial Ecology packages, especially Brightway, much easier. It guides GitHub Copilot to the right package documentation for your question, so you avoid mixed package versions, wrong references, and hallucinated answers.

An MCP (Model Context Protocol) server that explains Industrial Ecology Python packages through their documentation. Ask it anything about a registered package — installation, usage, API, concepts — directly from VS Code Copilot.

An MCP server is a bridge between Copilot and trusted external information. In VS Code Agent mode, Copilot can call this server to check package docs, source code, and versions before it answers.

Currently supported packages: The full Brightway LCA ecosystem, and additional industrial ecology tools — 56 packages total (see Brightway ecosystem and Additional packages below)

Why?

For modelling work, you need reliable help that matches your real environment and package versions. This server gives environment- and version-relevant explanations for both single functions and complete IE package workflows. This makes going through pages of package documentation and checking its GitHub pages redundant. Copilot can access information about the package and get relevant explantion/coding help for the exact package version you are using.

Example questions

• "How do I do a basic LCA in Brightway from setup to first result?"
• "How do I use premise for prospective LCA scenarios?"
• "How do I use the function [...]?
• "Explain what arguments the function takes in the package version that is currently installed in my environment."
• ...

---

Prerequisites

Run the following in your environment:

pip install "mcp[cli]>=1.0.0" "httpx>=0.27.0" "beautifulsoup4>=4.12.0" "markdownify>=0.13.0"

---

Setup

1. Clone the repo

git clone https://github.com/JonasKlimt/ie_mcp.git
cd ie-mcp

2. Connect to your AI client

VS Code (Copilot agent mode)

1st Option: Use the mcp server from within this clonded (which then becomes your local) repository

The .vscode/mcp.json file is already configured. Open this folder as your workspace root in VS Code and Copilot agent mode picks up the server automatically — no manual startup needed. This is recommended if you just want to get answers for questions.

2nd Option: Use the mcp server in your project

If you want to use the server in your project to answer questions and help you code, you need to add the following to your project. The server will still run in the local cloned repository but you will have access to it within your project.

Other workspaces / projects: To use the server from a different project, add it to your VS Code user settings (settings.json) with an absolute path:

{
  "mcp.servers": {
    "ie-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/your/environment/python.exe",
      "args": ["run", "/absolute/path/to/ie-mcp/server.py"],
      "env": {
         "GITHUB_TOKEN" : ""
      }
    }
  }
}

3. Point the server at the right Python environment

The server checks your installed package versions to look up the correct documentation and source code. It can only see packages installed in the Python interpreter specified in mcp.json (or user settings.json).

Your working environment: set command to the same Python executable you use for your work. E.g.: conda (C:\Users\you\miniconda3\envs\bw\python.exe), venv in project folder (./venv/Scripts/python.exe)

For best results, also add the instruction file (.github/copilot-instructions.md) in the .github folder to you repository. An instruction file is a short set of project-specific rules for Copilot (what tools to prefer, how to answer, what context matters most). This makes ie_mcp more efficient because Copilot is guided to use the server consistently and query package docs/versions in the way you want.

---

GitHub token (optional)

The search_source and get_function_source tools use the GitHub REST API. Without a token, GitHub allows 60 requests/hour — enough for light use. Add a free personal access token to raise the limit to 5 000 requests/hour.

1. Go to github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click Generate new token (classic), give it a name, set an expiry — no scopes needed for public repos.
3. Add the token to your client config:

VS Code — paste into .vscode/mcp.json:

{
  "mcp.servers": {
    "ie-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/your/environment/python.exe",
      "args": ["run", "/absolute/path/to/ie-mcp/server.py"],
      "env": {
        "GITHUB_TOKEN" : "ghp_your_token"
      }
    }
  }
}

Important: Do not commit .vscode/mcp.json after adding your token. The empty-token version is checked in so other users get a working starting point; your filled-in version is for local use only.

How the server works

1. It checks your active Python environment and installed package versions.
2. It fetches official documentation pages when needed and keeps a local cache for faster repeated use.
3. For version-specific questions, it checks GitHub tags first and then fetches matching source code.
4. When versioned docs are available (for example on ReadTheDocs), it can fetch those too.
5. If versioned docs are not available, it still answers from the matching versioned source code.

This keeps answers reliable, version-correct, and grounded in official docs or source.

---

Brightway ecosystem

Brightway is an open-source Python framework for life cycle assessment (LCA). All packages from the brightway-lca GitHub organisation are registered:

Meta-packages

Package key	PyPI / install	Description
brightway25	pip install brightway25	Brightway 2.5 — current stable meta-package
brightway2	pip install brightway2	Brightway 2 — legacy stable meta-package

Brightway 2.5 core components

These are the direct dependencies installed by pip install brightway25:

Package key	PyPI name	Role
bw2data	bw2data	Project & database management
bw2calc	bw2calc	LCA matrix calculations
bw2io	bw2io	Import / export (ecoinvent, SimaPro, …)
bw2analyzer	bw2analyzer	Contribution analysis & supply chain traversal
bw2parameters	bw2parameters	Parameter storage & formula evaluation
bw_processing	bw_processing	Structured NumPy datapackages
matrix_utils	matrix_utils	MappedMatrix building from datapackages
bw_migrations	bw_migrations	Migration files between ecoinvent versions
bw_simapro_csv	bw_simapro_csv	SimaPro CSV parsing
ecoinvent_interface	ecoinvent_interface	Programmatic ecoinvent download
multifunctional	multifunctional	Multi-output / allocation handling
randonneur	randonneur	Flexible dataset transformation engine
randonneur_data	randonneur_data	Transformation data files for randonneur
stats_arrays	stats_arrays	Uncertain parameter arrays & Monte Carlo
mrio_common_metadata	mrio_common_metadata	MRIO datapackage schema

Additional brightway-lca packages

Package key	Description
bw_temporalis	Time-explicit LCA (Brightway 2.5)
bw_timex	Advanced time-explicit LCA
dynamic_characterization	Dynamic (time-dependent) characterization factors
bw_graph_tools	Supply chain graph traversal utilities
bw_exiobase	EXIOBASE MRIO import
bw_recipe_2016	ReCiPe 2016 LCIA method
bw_aggregation	Aggregated process support
bw_campaigns	Named datapackage campaign management
bw_hestia_bridge	HESTIA API bridge
bw_interface_schemas	Pydantic interface schemas
bw_simple_graph	Lightweight graph backend (no bw2data)
edge_of_the_world	Experimental backend for richer exchange descriptions beyond standard matrix structure
brightway2_regional	Regionalized LCA calculations
brightway_olca	openLCA IPC server integration
brightway_hybrid	Hybrid IO/process LCA
ecoinvent_migrate	Randonneur migration file generator
pedigree_matrix	Pedigree-matrix uncertainty adaptation
pyecospold	EcoSpold1/2 XML ↔ Python round-trip
pyilcd	ILCD XML ↔ Python round-trip
simapro_ecoinvent_elementary_flows	SimaPro ↔ ecoinvent flow mappings
simple_regional	Lightweight regionalized LCA
brightway2_speedups	Cython performance extensions for BW2
brightway2_ui	CLI tool for Brightway2

---

Additional packages

LCA tools

Package key	GitHub	Docs	Description
edges	edges	readthedocs	Edge-based LCIA for Brightway: context-sensitive characterization factors applied to exchanges, not just flows. Includes AWARE 2.0, ImpactWorld+, GeoPolRisk, GLAM3.
lca_algebraic	lca_algebraic	readthedocs	Parametric LCA inventories with fast Monte Carlo and Sobol sensitivity analysis, using Sympy expressions. Built on Brightway2/2.5.
pathways	pathways	readthedocs	Scenario-driven transformations for LCI datasets and workflows, designed for prospective and pathway-based LCA use cases.
regioinvent	Regioinvent	GitHub README	Automatically regionalizes ecoinvent by connecting it to the BACI trade database, creating national production processes and consumption markets.

Material flow analysis (MFA)

Package key	GitHub	Docs	Description
flodym	flodym	readthedocs	Flexible Open Dynamic Material Systems Model — Python library for dynamic MFA with dimension-aware arrays (FlodymArray), stock accumulation with age-cohort tracking, and Pydantic-typed system setup. Adaptation of ODYM.
odym	ODYM	readthedocs	Open Dynamic Material Systems Model — Python framework for dynamic material flow analysis with object-based system description and dynamic stock modeling.
recc_odym	RECC-ODYM	GitHub README	Resource Efficiency–Climate Change mitigation model built on ODYM. Dynamic MFA of vehicles and buildings across SSP scenarios; assesses 10 material efficiency strategies.

Environmentally extended input output analysis

Package key	GitHub	Docs	Description
pymrio	pymrio	readthedocs	Multi-regional input-output (EE MRIO) analysis: auto-download and parse EXIOBASE, WIOD, EORA26, OECD, GLORIA; calculate footprints, trade-embodied impacts.

---

Adding a new package

Let us know if you are missing any package! You can also add an addtional package yourself:

1. Create packages/{name}/ with an __init__.py.
2. Create packages/{name}/metadata.py with a METADATA dict. Copy packages/premise/metadata.py as a template — the key fields are:
   • name, description, github_url, github_repo, readthedocs_slug, docs_url, install, sections
   • Each section needs id, title, url, description.
3. Run the fetch script: python scripts/fetch_docs.py --package {name}
4. Restart the server — the new package is discovered automatically.

No changes to server.py or any core file are needed.

Contibutions are welcome!

---

License

BSD-3-Clause