Climatiq
    Climatiq

    Climatiq

    A Model Context Protocol (MCP) server for accessing the Climatiq API to calculate carbon emissions. This allows AI assistants to perform real-time carbon calculations and provide climate impact insights.

    4.3

    GitHub Stats

    Stars

    4

    Forks

    5

    Release Date

    6/9/2025

    about a month ago

    Detailed Description

    climatiq mcp server

    license: mit

    a model context protocol (mcp) server for accessing the climatiq api to calculate carbon emissions. this allows ai assistants to perform real-time carbon calculations and provide climate impact insights.

    demo

    https://github.com/user-attachments/assets/c253d6d1-ccf6-4c14-965e-6023ba2a0296

    https://github.com/user-attachments/assets/d61c1181-acf6-4d9f-9a48-537fc64ac4c3

    features

    this mcp server integrates with the climatiq api to provide carbon emission calculations for ai assistants:

    tools

    • set-api-key: configure the climatiq api key used for authentication
    • electricity-emission: calculate carbon emissions from electricity consumption
    • travel-emission: calculate carbon emissions from travel by car, plane, or train
    • search-emission-factors: search for specific emission factors in the climatiq database
    • custom-emission-calculation: perform custom calculations using specific emission factors
    • cloud-computing-emission: calculate emissions from cloud computing resources usage
    • freight-emission: calculate emissions from freight transportation
    • procurement-emission: calculate emissions from procurement spending
    • hotel-emission: calculate emissions from hotel stays
    • travel-spend: calculate emissions from travel expenses

    resources

    • carbon calculation results are exposed as resources with a climatiq://calculation/{id} uri scheme
    • each resource contains detailed information about an emission factor and calculation results

    prompts

    • climate-impact-explanation: generate natural language explanations about the climate impact of specific emission calculations

    installation

    from source

    this project uses uv for virtual environment and dependency management. make sure to install uv first.

    # clone the repository
    git clone https://github.com/your-org/climatiq-mcp-server.git
    cd climatiq-mcp-server
    
    # create a virtual environment
    uv venv
    
    # activate the virtual environment
    # on macos/linux:
    source .venv/bin/activate
    # on windows:
    .venv\scripts\activate
    
    # install dependencies with development extras
    uv sync --dev --extra all
    

    using uv

    uv pip install climatiq-mcp-server
    

    api key configuration

    the server requires a climatiq api key to function. you have several options to provide it:

    1. environment variable: set the climatiq_api_key environment variable before starting the server

      export climatiq_api_key=your_climatiq_api_key
      
    2. configuration during installation:

      climatiq_api_key=your_climatiq_api_key uv pip install climatiq-mcp-server
      
    3. set-api-key tool: use the set-api-key tool to configure it during runtime within the ai assistant

    4. configuration file: create a .env file in the project directory:

      climatiq_api_key=your_climatiq_api_key
      

    to get a climatiq api key:

    1. sign up at app.climatiq.io
    2. follow the instructions at getting api keys

    running the server

    the server can be started directly from the command line:

    climatiq-mcp-server
    

    setup in ai assistants

    claude desktop

    on macos: ~/library/application\ support/claude/claude_desktop_config.json on windows: %appdata%/claude/claude_desktop_config.json

    "mcpservers": {
      "climatiq-mcp-server": {
        "command": "climatiq-mcp-server",
        "env": {
          "climatiq_api_key": "your_climatiq_api_key"
        }
      }
    }
    

    examples and utilities

    examples directory

    the examples/ directory contains:

    • climatiq.ipynb: a jupyter notebook demonstrating direct api usage with climatiq
    • simple_test.py: a simple utility for testing the api integration directly without mcp protocol
    # run the simple test
    python examples/simple_test.py
    

    utility scripts

    the utils/ directory contains several helpful scripts:

    test client

    the test_client.py script tests all the tools, prompts, and resources:

    python utils/test_client.py
    

    llm example client

    the llm_example_client.py script demonstrates how a large language model (like claude) could interact with the climatiq mcp server:

    python utils/llm_example_client.py
    

    key features:

    • complete api wrapper with error handling and timeout management
    • resource and result caching to preserve calculation history
    • example prompts showing how to generate natural language explanations
    • demonstrates electricity emission, travel emission, and emission factor search capabilities

    cli tool

    a command-line interface tool for direct api access without the mcp server complexity:

    # for electricity emissions
    python utils/climatiq_cli.py electricity --energy 1000 --unit kwh --region us
    
    # for travel emissions
    python utils/climatiq_cli.py travel --mode car --distance 100 --unit km --region us
    

    run mcp server script

    use the run_mcp_server.py script to directly run the server without installing:

    python utils/run_mcp_server.py
    

    key concepts

    activity ids

    an activity id is a key concept in climatiq's api that groups similar emission factors together:

    • each emission factor in the climatiq database has an activity id
    • activity ids group emission factors describing the same activity across regions, years, sources, etc.
    • examples: electricity-supply_grid-source_residual_mix (electricity), passenger_vehicle-vehicle_type_car (car travel)

    calculation methods

    the climatiq mcp server supports multiple calculation methods:

    1. distance-based method for travel emissions
    2. advanced travel calculations with origin-destination pairs
    3. spend-based method for when you only have expenditure data
    4. direct calculations using specific emission factors

    troubleshooting

    api key issues

    1. ensure climatiq_api_key is set correctly in your environment or .env file
    2. verify the api key is active in your climatiq dashboard
    3. use examples/simple_test.py to check if your api key works correctly

    advanced usage

    for detailed documentation on using specific tools and advanced features, see the docs/readme.md file.

    about climatiq

    climatiq provides a powerful api for carbon intelligence, allowing you to calculate emissions from electricity usage, transportation, procurement, and more. this mcp server makes those capabilities accessible to ai assistants through the model context protocol.

    for more information about climatiq, visit climatiq.io.

    license

    this project is licensed under the mit license - see the license file for details.

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.