Climatiq MCP server for AI agents

The Climatiq MCP server integrates with the Climatiq API to enable AI assistants to perform real-time carbon emission calculations and provide climate impact insights. It offers tools for calculating emissions from electricity, travel, cloud computing, and more, making climate data accessible through the Model Context Protocol.

Installation Options

Installing from Source

This project uses uv for virtual environment and dependency management.

# 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

Installing with uv

uv pip install climatiq-mcp-server

API Key Configuration

The server requires a Climatiq API key to function properly. You can provide it in several ways:

Environment Variable:

export CLIMATIQ_API_KEY=your_climatiq_api_key

Configuration During Installation:

CLIMATIQ_API_KEY=your_climatiq_api_key uv pip install climatiq-mcp-server

Configuration File: Create a .env file in the project directory:
```
CLIMATIQ_API_KEY=your_climatiq_api_key
```
Set API Key Tool: Use the set-api-key tool during runtime within the AI assistant

To get a Climatiq API key:

Sign up at app.climatiq.io
Follow the instructions at Getting API Keys

Running the Server

Start the server with the following command:

climatiq-mcp-server

Setting Up in AI Assistants

Claude Desktop

Add the server configuration to your Claude configuration file:

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration example:

"mcpServers": {
  "climatiq-mcp-server": {
    "command": "climatiq-mcp-server",
    "env": {
      "CLIMATIQ_API_KEY": "your_climatiq_api_key"
    }
  }
}

Available Tools

The MCP server provides several tools for carbon calculations:

set-api-key: Configure the Climatiq API key
electricity-emission: Calculate emissions from electricity consumption
travel-emission: Calculate emissions from car, plane, or train travel
search-emission-factors: Search for specific emission factors
custom-emission-calculation: Perform custom calculations with specific factors
cloud-computing-emission: Calculate emissions from cloud resource 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

Using the Testing Utilities

Testing All Features

Test all tools, prompts, and resources using:

python utils/test_client.py

CLI Tool for Direct Access

Access Climatiq functionality directly from the command line:

# 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

Running the Server Without Installation

Use the provided script to run the server directly:

python utils/run_mcp_server.py

Key Concepts

Activity IDs

Activity IDs group similar emission factors together in the Climatiq database. Examples include:

electricity-supply_grid-source_residual_mix (for electricity)
passenger_vehicle-vehicle_type_car (for car travel)

Calculation Methods

The server supports multiple calculation approaches:

Distance-based calculations for travel emissions
Origin-destination pairs for advanced travel calculations
Spend-based calculations for expenditure data
Direct calculations with specific emission factors

Troubleshooting

If you encounter API key issues:

Verify CLIMATIQ_API_KEY is set correctly
Check if the API key is active in your Climatiq dashboard
Use examples/simple_test.py to test your API key

For more information about Climatiq, visit climatiq.io.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.