ie-mcp
This MCP server helps AI assistants answer questions about Industrial Ecology/Brightway Python packages by inspecting the local Python environment, package versions, documentation, and source code.
List registered packages and inspect the Python environment/interpreter and installed package versions.
Get package metadata, including description, URLs, install commands, and available documentation sections.
List documentation versions, read specific documentation sections, search documentation, and force-refresh cached docs.
List source versions from GitHub tags, search package source code, and retrieve exact function/method/class source with signature and docstring for the installed or a specified version.
Keep answers tied to the user’s actual installed versions and cited sources, reducing version mismatches and hallucinated package details.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ie-mcp How do I use brightway2 to create a database?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ie_mcp
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.
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.
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 | shThen 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-mcpDo 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-mcpThen 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:
Open Settings and select MCP servers.
Select Add server.
Name:
ie-mcp. Type: STDIO. Command:uvx. Arguments:--from,git+https://github.com/JonasKlimt/ie_mcp,ie-mcp.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-mcpThe 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.
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 |
| Always start with this Python executable as the environment to inspect, for example |
| Folder for downloaded docs and source files. Default: |
| Days that the docs of |
| 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 |
|
Codex |
|
GitHub Copilot (VS Code) | a new |
## 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 |
| All packages with a one-line description and the installed version |
| Choose and inspect the Python environment (every other tool also accepts |
| Installed version of one package |
| Signature, docstring and code of a function, method or class, and a text search, for the installed version or any other version |
| Available versions, and what changed between them (GitHub releases or changelog file) |
| Package metadata and the pages of its documentation (long pages are read in parts) |
| Ranked search over all documentation pages of a package |
| 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.
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 |
|
|
| the exact version the code comes from |
| what is installed in your environment (or |
| the file the code was read from |
| for search results from your installed files: the folder the |
| 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)
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.
Go to github.com → Settings → Developer settings → Personal access tokens → Tokens (classic)
Click Generate new token (classic), give it a name, set an expiry. No scopes are needed for public repos.
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"
}
}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
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.
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.
Other versions from PyPI. If you ask about another version, that exact release is downloaded from PyPI once and cached.
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.Docs for context. Official documentation pages are fetched when needed and cached for a week (
latestandstable; 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.What changed?
get_changelogreads the release notes from GitHub, or the changelog file of the repository, for the versions after the one you have installed.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 |
|
| Brightway 2.5 — current stable meta-package |
|
| 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 | Project & database management |
| bw2calc | LCA matrix calculations |
| bw2io | Import / export (ecoinvent, SimaPro, …) |
| bw2analyzer | Contribution analysis & supply chain traversal |
| bw2parameters | Parameter storage & formula evaluation |
| bw_processing | Structured NumPy datapackages |
| matrix_utils | MappedMatrix building from datapackages |
| bw_migrations | Migration files between ecoinvent versions |
| bw_simapro_csv | SimaPro CSV parsing |
| ecoinvent_interface | Programmatic ecoinvent download |
| multifunctional | Multi-output / allocation handling |
| randonneur | Flexible dataset transformation engine |
| randonneur_data | Transformation data files for randonneur |
| stats_arrays | Uncertain parameter arrays & Monte Carlo |
| mrio_common_metadata | MRIO datapackage schema |
Additional brightway-lca packages
Package key | Description |
| Time-explicit LCA (Brightway 2.5) |
| Advanced time-explicit LCA |
| Dynamic (time-dependent) characterization factors |
| Supply chain graph traversal utilities |
| EXIOBASE MRIO import |
| ReCiPe 2016 LCIA method |
| Aggregated process support |
| Named datapackage campaign management |
| HESTIA API bridge |
| Pydantic interface schemas |
| Lightweight graph backend (no bw2data) |
| Experimental backend for richer exchange descriptions beyond standard matrix structure |
| Regionalized LCA calculations |
| openLCA IPC server integration |
| Hybrid IO/process LCA |
| Randonneur migration file generator |
| Pedigree-matrix uncertainty adaptation |
| EcoSpold1/2 XML ↔ Python round-trip |
| ILCD XML ↔ Python round-trip |
| SimaPro ↔ ecoinvent flow mappings |
| Lightweight regionalized LCA |
| Cython performance extensions for BW2 |
| CLI tool for Brightway2 |
Additional packages
LCA tools
Package key | GitHub | Docs | Description |
| Edge-based LCIA for Brightway: context-sensitive characterization factors applied to exchanges, not just flows. Includes AWARE 2.0, ImpactWorld+, GeoPolRisk, GLAM3. | ||
| Parametric LCA inventories with fast Monte Carlo and Sobol sensitivity analysis, using Sympy expressions. Built on Brightway2/2.5. | ||
| Scenario-driven transformations for LCI datasets and workflows, designed for prospective and pathway-based LCA use cases. | ||
| 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 |
| 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. | ||
| Open Dynamic Material Systems Model — Python framework for dynamic material flow analysis with object-based system description and dynamic stock modeling. | ||
| 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 |
| 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:
Create
packages/{name}/with an__init__.py.Create
packages/{name}/metadata.pywith aMETADATAdict. Copypackages/premise/metadata.pyas a template — the key fields are:name,description,github_url,github_repo,readthedocs_slug,docs_url,install,sectionsEach section needs
id,title,url,description.
Run the fetch script:
python scripts/fetch_docs.py --package {name}Restart the server — the new package is discovered automatically.
Optional: add the package to a group under
check_firstincore/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 toolsfetch_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
An MCP server that gives your AI access to the source code and docs of all public github repos
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA 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 PyPI14MIT
- AlicenseNot gradedqualityCmaintenanceAn 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

GitHitsofficial
AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to search and access open-source code, documentation, and package information via a local MCP server.1,577 npm139Apache 2.0
Vibgrate AI Contextofficial
AlicenseNot gradedqualityBmaintenanceLocal-first MCP server that gives AI assistants codebase intelligence—code graph, drift analysis, vulnerability attribution, and version-correct library docs—all from the user's machine.1,093 npm6Apache 2.0