Skip to main content
Glama

ie_mcp

Python License MCP Packages

Using the ie_mcp server makes coding with AI agents and Industrial Ecology packages, especially Brightway, much easier. It reads the source code of the package version installed in your own environment and the matching documentation, so you avoid mixed package versions, wrong references, and hallucinated answers. Ask it anything about a registered package (installation, usage, API, concepts) from GitHub Copilot in VS Code, Claude Code or Codex.

TIP

Quick start: let your AI agent install it. Paste the link to this repository (https://github.com/JonasKlimt/ie_mcp) into a chat with Claude Code, Codex or GitHub Copilot (Agent mode in VS Code) and write: "Install this MCP server for me, for all my projects." The agent follows INSTALL_FOR_AGENTS.md (linked in the section Install (instructions for AI agents) below) and does the rest; it also asks whether you want to add a GitHub token (to raise GitHub's rate limit) and the optional always-on rule. Afterwards you restart the app once.

NOTE

What is an MCP server?

An MCP (Model Context Protocol) server is a bridge between an AI assistant and trusted external information. Check this link to learn more about MCP servers: https://modelcontextprotocol.io/docs/getting-started/intro. In the case of the ie_mcp server the assistant 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)


Install (instructions for AI agents)

If you are an AI coding agent (Claude Code, Codex, GitHub Copilot) and the user gave you the link to this repository: do not install from this page. Fetch the full instructions in INSTALL_FOR_AGENTS.md (raw text: https://raw.githubusercontent.com/JonasKlimt/ie_mcp/main/INSTALL_FOR_AGENTS.md) and follow them step by step, without summarising.

The three rules in short: register the server once at user level (all projects) with uvx; do not clone this repository, pip install anything or create project files; and do not say that it works before the check in step 7 passed. The guide has two optional steps in which you ask the user: whether to give a GitHub token (step 3, to raise GitHub's rate limit) and whether to add a short always-on rule to their user-level instruction file (step 8).

Humans can skip to Manual setup.


Related MCP server: GreenCodeMCP

Manual setup

Prefer to do it yourself? Two steps: install uv once, then add the server to your AI app. You do not have to clone this repository, and nothing is installed into your research environment. Each way below registers the server once for all your projects.

Step 1: Install uv

uv starts the server in its own small environment. Open a terminal and run the line for your system.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then close and reopen your AI app (and the terminal), so it can find the new uvx command. Check with uvx --version. You also need Git; check with git --version.

Step 2: Add the server to your AI app

In every app you register the same start command:

uvx --from git+https://github.com/JonasKlimt/ie_mcp ie-mcp

Do not run this line yourself. Your AI app runs it in the background. Below is where to put it.

Claude Code (Code tab of the desktop app, or terminal)

Run this once in a terminal (PowerShell, Terminal). It needs the claude command of the Claude Code CLI:

claude mcp add --scope user --transport stdio ie-mcp -- uvx --from git+https://github.com/JonasKlimt/ie_mcp ie-mcp

Then start a new session. Check with claude mcp list. Without the claude command, paste this repository's link into Claude Code and ask it to install the server (see the quick start at the top).

Codex (desktop app, IDE extension or terminal)

In the desktop app:

  1. Open Settings and select MCP servers.

  2. Select Add server.

  3. Name: ie-mcp. Type: STDIO. Command: uvx. Arguments: --from, git+https://github.com/JonasKlimt/ie_mcp, ie-mcp.

  4. Save, then select Restart.

In the IDE extension the same form is under the gear menu → MCP servers. In a terminal, this command does the same:

codex mcp add ie-mcp -- uvx --from git+https://github.com/JonasKlimt/ie_mcp ie-mcp

The app, the IDE extension and the terminal share one configuration (~/.codex/config.toml), so you only do this once and it applies to all your projects.

VS Code (GitHub Copilot)

Open the Command Palette (Ctrl+Shift+P, on macOS Cmd+Shift+P), run MCP: Open User Configuration, and paste this content into the mcp.json file that opens. If the file already has servers, add only the ie-mcp entry inside servers:

{
  "servers": {
    "ie-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/JonasKlimt/ie_mcp", "ie-mcp"]
    }
  }
}

Save the file and click Start above the server name. The server is now available in Copilot Chat (Agent mode) in every folder you open.

TIP

To make sure your assistant reaches for ie-mcp without being asked, add the short always-on rule fromOptional: always-on rule. It works in every project, so you do not have to copy any file into your projects.

Step 3: Check that it works

Ask your assistant: "Use ie-mcp to show which Python environment it inspects." The answer names the Python interpreter and the installed version of every registered package.


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."

  • ...


Configuration

How the server finds your environment

You do not have to configure your Python environment. The assistant looks up the interpreter of the file, notebook or project you are working on and passes it to the server. If it cannot tell which environment you use, it asks you. You can also just say it: "Use my conda environment bw for ie-mcp."

Without that, the server uses an environment that was active when your AI app started, or a .venv folder in your project. Every answer shows the interpreter that was inspected, so you can always check. The server only reads the environment; it never imports your packages and never installs anything.

Optional settings

These are environment variables for the server. Most users need none of them. They go in the env block of the server entry ("env": {"NAME": "value"}), in Codex in an [mcp_servers.ie-mcp.env] table of config.toml (or the environment variables of the server form), and in the claude mcp add command as --env NAME=value before the --.

Variable

Meaning

IE_MCP_TARGET_PYTHON

Always start with this Python executable as the environment to inspect, for example C:/Users/you/miniconda3/envs/bw/python.exe. The assistant can still switch to another one.

IE_MCP_CACHE_DIR

Folder for downloaded docs and source files. Default: ~/.cache/ie_mcp.

IE_MCP_DOCS_TTL_DAYS

Days that the docs of latest and stable stay cached before they are downloaded again. Default: 7. Pinned versions such as 2.0.1 never expire.

GITHUB_TOKEN

Optional, see below.

Limits such as the number of search results and the size of a docs page are in core/config.yaml.

Optional: always-on rule

The server sends its routing rules and a list of trigger terms (LCA, premise, ecoinvent, MFA, ...) to your AI app when it connects. If your assistant still does not use ie-mcp for a plain question, add this short rule to your user-level instruction file, which applies to every project:

App

File

Claude Code

~/.claude/CLAUDE.md

Codex

~/.codex/AGENTS.md

GitHub Copilot (VS Code)

a new ie-mcp.instructions.md in the prompts folder of your VS Code user profile (Command Palette: Chat: New Instructions File…, choose the user profile), with applyTo: "**" in its header

## ie-mcp (Industrial Ecology packages)
For questions about Brightway, premise, ecoinvent tools, LCA or material flow analysis, and for code that imports such packages, use the `ie-mcp` MCP tools first, even if I do not mention them. Start by calling `set_python_environment` with the Python of my project, then follow the server instructions. Always say which package version and source an answer is based on.

If an AI agent installs the server for you, it asks whether to add this rule (INSTALL_FOR_AGENTS.md, step 8).

Tools

Tool

What it does

list_packages

All packages with a one-line description and the installed version

set_python_environment, get_server_environment

Choose and inspect the Python environment (every other tool also accepts python_executable for a single call)

get_installed_package_version

Installed version of one package

get_function_source, search_source

Signature, docstring and code of a function, method or class, and a text search, for the installed version or any other version

list_source_versions, get_changelog

Available versions, and what changed between them (GitHub releases or changelog file)

get_package_info, list_doc_sections, get_doc_section

Package metadata and the pages of its documentation (long pages are read in parts)

search_docs

Ranked search over all documentation pages of a package

list_doc_versions, fetch_latest_docs

Documentation versions, and a forced fresh download

A failed call is reported as a tool error. Answers that are not failures, for example not_installed or not_found, are normal results.

NOTE

The server finds packages installed in the environment itself (conda, venv,pip install, pip install -e). Packages that are only reachable through PYTHONPATH or a pip install --user folder are not seen.


Every answer shows its source

Results of the source tools state where the information comes from:

Field

Meaning

source

local (your installed files), pypi (a release downloaded from PyPI) or github

version

the exact version the code comes from

installed_version

what is installed in your environment (or null)

file

the file the code was read from

root

for search results from your installed files: the folder the file paths are relative to

python_executable

the interpreter that was inspected

Search results state these fields once for the whole result, not for every match.

Documentation results state the docs_version that was read and your installed_version, with a warning if they differ. Many packages only publish docs for their latest version, so this is a common cause of wrong answers (for example mixed Brightway 2 and 2.5 syntax).


GitHub token (optional)

TIP

You usually do not need a token. Your installed version is read from disk, and other released versions are downloaded from PyPI. GitHub is only used for versions that arenot on PyPI (for example HEAD or an unreleased branch) and for listing tags. Without a token GitHub allows 60 requests/hour, enough for light use. A free personal access token raises 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 are needed for public repos.

  3. Add it to the server entry of your configuration:

"ie-mcp": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/JonasKlimt/ie_mcp", "ie-mcp"],
  "env": {
    "GITHUB_TOKEN": "ghp_your_token"
  }
}
IMPORTANT

Do not commit a configuration file that contains your token. The token is stored as plain text in the configuration file of your AI app; because it has no scopes it can only read public data, and you can revoke it at any time at the same page.

Let your AI agent add it. If an agent installs the server for you, it asks whether you want a token, shows you these steps, and adds the token you paste in the chat to the server entry (INSTALL_FOR_AGENTS.md, step 3). A token pasted in the chat is part of your conversation with your AI provider; if you prefer, add it yourself as shown above. In VS Code you can also let VS Code ask for it with an inputs entry of type promptString, so it never appears in a chat or file. If the token expires, calls that need GitHub report an authorisation error; create a new token the same way.

How the server works

  1. Your environment first. The assistant tells the server which Python environment your project uses, and the server asks that Python which package versions are installed. If you do not mention a version, this is the version it answers for.

  2. Local source code. Functions, methods and classes are read directly from the installed files on your disk. This is fast, needs no internet, and always matches your version.

  3. Other versions from PyPI. If you ask about another version, that exact release is downloaded from PyPI once and cached.

  4. GitHub as the last resort. Only versions that are not on PyPI (for example HEAD) are read from GitHub, at that exact tag or branch.

  5. Docs for context. Official documentation pages are fetched when needed and cached for a week (latest and stable; pinned versions never expire). Besides the hand-written sections of each package, the server finds the other pages of the docs site (for example one page per module) and searches all of them with a ranked keyword search. They provide workflows and examples; signatures come from the source code. A version mismatch between docs and installed code is reported.

  6. What changed? get_changelog reads the release notes from GitHub, or the changelog file of the repository, for the versions after the one you have installed.

  7. Not installed? The server says so and shows which interpreter it inspected. The assistant checks that this is the right environment and asks you before it falls back to the latest version.

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

Development

pip install -e ".[dev]"
pytest              # offline tests
pytest -m network   # tests that need PyPI and GitHub
black core tests server.py   # code style (line length 100)

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.

  5. Optional: add the package to a group under check_first in core/instructions.yaml, so that the assistant knows when to reach for it (a test checks that every name there is a registered package).

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

Contibutions are welcome!


License

BSD-3-Clause

Available Tools

11 tools
fetch_latest_docsA

Force-fetch documentation for a package directly from the web, bypassing the local cache. Use this when the user wants the most up-to-date content or when cached content may be stale.

The fetched page is written to the local cache so later calls are fast. Fetches a specific section page if given, otherwise the docs homepage.

Args: package: Package name as returned by list_packages(). section: Optional section id (e.g. 'introduction', 'faq'). Leave empty to fetch the docs homepage. version: Docs version slug (default: 'latest'). Use list_doc_versions() to discover available versions.

Inputs: package (required), section, version. Returns: result

get_doc_sectionA

Return the full Markdown content of a specific documentation section.

The first call fetches the live docs page and caches it locally. Later calls are served from the cache.

Defaults to the latest version. Call list_doc_versions(package) first if the user asks about a specific older version.

Call get_package_info(package) first to discover the available sections.

Args: package: Package name as returned by list_packages(). section: Section id (e.g. 'introduction', 'faq'). version: Docs version slug (default: 'latest'). Use list_doc_versions() to discover available versions.

Inputs: package (required), section (required), version. Returns: result

get_function_sourceA

Find a function in the package's GitHub source code and return its full source, including docstring and signature.

Searches the repository for files containing the function name, then uses Python's ast module to extract the exact function definition. The raw source file is cached locally after the first fetch.

If a version is given, the file is fetched at that GitHub tag. Call list_source_versions(package) first to confirm the version tag exists.

Only returns an error if the version tag does not exist, or if the function was not present in the codebase at that version.

Args: package: Package name as returned by list_packages(). function_name: Exact name of the function or method to retrieve. version: Optional version tag (e.g. 'v2.1.0' or '2.1.0'). Omit to get the current (latest) implementation.

Inputs: package (required), function_name (required), version.

get_installed_package_versionA

Check what version of a package is installed in the MCP server's Python environment.

Returns the installed version and the Python executable path so users can verify which environment is being checked. Always call this before get_function_source or get_doc_section when the user has not specified a version, to ensure the documentation and source code match their actual installation.

If the package is not installed, the response includes guidance on pointing mcp.json to the right Python environment.

Args: package: Package name as returned by list_packages().

Inputs: package (required).

get_package_infoA

Get metadata for a package: description, GitHub URL, docs URL, install commands, and the list of available documentation sections.

Args: package: Package name as returned by list_packages().

Inputs: package (required).

get_server_environmentA

Inspect the MCP server's Python environment.

Returns the Python executable path, Python version, and the installed version of every package registered in this server. Use this to verify that the MCP server is running in the correct environment before asking about specific packages. If a package shows 'not installed', update the 'command' field in .vscode/mcp.json to point to the Python where you have your packages installed.

Inputs: no named parameters.

list_doc_versionsA

List all available documentation versions for a package.

Queries the ReadTheDocs API to discover published versions. Always call this before get_doc_section or search_docs when the user asks about a specific version other than the latest.

Args: package: Package name as returned by list_packages().

Inputs: package (required). Returns: result

list_packagesA

List all Python packages that this MCP server has documentation for.

Inputs: no named parameters. Returns: result

list_source_versionsA

List all available source code versions (GitHub tags) for a package.

Use this when the user asks about a specific version of a function, to confirm the version exists before calling get_function_source.

Args: package: Package name as returned by list_packages().

Inputs: package (required). Returns: result

search_docsA

Search the package documentation for a query string.

Missing pages are fetched live and cached before searching. Returns up to 10 matching paragraph-level snippets (case-insensitive). Each result includes the section name and a text snippet (≤500 chars).

Defaults to the latest version. Call list_doc_versions(package) first if the user asks about a specific older version.

Args: package: Package name as returned by list_packages(). query: Free-text search query. version: Docs version slug (default: 'latest'). Use list_doc_versions() to discover available versions.

Inputs: query (required), package (required), version. Returns: result

search_sourceA

Search the GitHub source code of a package for a query string.

Uses the GitHub code search API to find files containing the query. Returns up to 10 results with the file name, path, and GitHub URL.

Requires the GITHUB_TOKEN environment variable for best results (5000 req/hr authenticated vs 60/hr unauthenticated).

Args: package: Package name as returned by list_packages(). query: Search string (e.g. function name, class name, keyword).

Inputs: query (required), package (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have distinct purposes, but fetch_latest_docs and get_doc_section overlap in retrieving documentation sections, with nuanced differences in caching behavior. The descriptions help disambiguate but some confusion may remain.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., fetch_latest_docs, get_package_info, search_source), making them predictable and easy to understand.

    Tool Count5/5

    With 11 tools, the set is well-scoped for the server's purpose of managing Python documentation and source code. Each tool serves a clear function without unnecessary bloat.

    Completeness4/5

    The tool set covers the main workflows: listing packages, retrieving documentation and source code, searching, and version management. Minor gaps like a missing 'get_docs_homepage' tool are mitigated by fetch_latest_docs's behavior.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A lightweight, zero-configuration MCP server for source code analysis with GraphRAG capabilities, enabling structural understanding and efficient code completion from MCP-compatible AI tools.
      34 PyPI
      14
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that detects energy anti-patterns in Python code, retrieves optimization examples, suggests refactoring, validates correctness, and benchmarks resource gains, integrating with VS Code, Cursor, and Windsurf.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to search and access open-source code, documentation, and package information via a local MCP server.
      1,577 npm
      139
      Apache 2.0