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 this is needed

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. Just as Copilot about the package and get relevant explantion/coding help for the exact package version you are using.

Related MCP server: projscan

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/YOUR_USERNAME/ie-mcp.git
cd ie-mcp

2. Connect to your AI client

VS Code (Copilot agent mode)

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.

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

Rule of thumb: set command to the same Python executable you use for your work.

Copilot will call get_server_environment() and return a full list of tracked packages with their installed versions, plus the active Python executable path. If a package shows "not installed", update command in mcp.json and restart the server.

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

Brightway 2.5 core components

These are the direct dependencies installed by pip install brightway25:

Additional brightway-lca packages

Additional packages

LCA tools

Material flow analysis (MFA)

Environmentally extended input output analysis

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.

License

The Unlicense (public domain dedication)