Climatiq MCP Server is a Model Context Protocol (MCP) server used to access the Climatiq API to calculate carbon emissions, enabling AI assistants to perform real-time carbon calculations and provide climate impact insights.
Purpose
The server exposes the Climatiq API's carbon calculation capabilities to AI assistants through the MCP protocol, enabling them to directly invoke carbon emission calculation functionality during conversations or tasks.
Main Capabilities
The MCP server integrates the Climatiq API and provides the following tools:
- set-api-key: Configure the Climatiq API key used for authentication.
- electricity-emission: Calculate carbon emissions generated by electricity consumption.
- travel-emission: Calculate carbon emissions from car, plane, or train travel.
- 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 generated by cloud computing resource usage.
- freight-emission: Calculate emissions generated by freight transport.
- procurement-emission: Calculate emissions generated by procurement spending.
- hotel-emission: Calculate emissions generated by hotel stays.
- travel-spend: Calculate emissions generated by travel expenses.
- climate-impact-explanation: Generate natural language explanations for specific emission calculations.
Carbon calculation results are exposed as resources with the URI scheme climatiq://calculation/{id}, and each resource contains detailed information about the emission factors and calculation results.
Usage
The project uses uv for virtual environment and dependency management, and uv must be installed first.
There are several ways to configure the API key:
- Environment variable: Set the CLIMATIQ_API_KEY environment variable before starting the server, for example
export CLIMATIQ_API_KEY=your_climatiq_api_key. - Configuration during installation:
CLIMATIQ_API_KEY=your_climatiq_api_key uv pip install climatiq-mcp-server. - At runtime, use the set-api-key tool to configure it in the AI assistant.
- Configuration file: Create a .env file in the project directory with the content
CLIMATIQ_API_KEY=your_climatiq_api_key.
Obtaining a Climatiq API key: Register at app.climatiq.io and follow the instructions in Getting API Keys.
The server can be started directly from the command line. To set it up in an AI assistant: the macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json, and the Windows path is %APPDATA%/Claude/claude_desktop_config.json.
The examples/ directory contains: climatiq.ipynb (a Jupyter notebook demonstrating direct use of the Climatiq API), simple_test.py (a simple tool for directly testing API integration without going through the MCP protocol).
The utils/ directory contains multiple utility scripts: test_client.py tests all tools, prompts, and resources; llm_example_client.py demonstrates how a large language model (such as Claude) interacts with the Climatiq MCP server; it also contains a complete API wrapper with error handling and timeout management, resources for retaining calculation history and result caching, example prompts for generating natural language explanations, demonstrations of electricity emissions and travel emissions and emission factor search capabilities, and a command-line interface tool for direct API access without the complexity of an MCP server. The run_mcp_server.py script can be used to run the server directly without installation.
Applicable Scenarios
Suitable for scenarios that require enabling AI assistants to perform carbon emission calculations, query emission factors, and generate natural language explanations of climate impact, covering emission categories such as electricity, travel, freight, procurement, cloud computing, and hotel stays.
Limitations
A valid Climatiq API key is required and must be configured correctly. The project uses uv to manage dependencies. If the API key is invalid or not set, the functionality cannot be used. Refer to troubleshooting: ensure CLIMATIQ_API_KEY is correctly set in the environment or .env file; verify in the Climatiq dashboard whether the API key is active; use examples/simple_test.py to check whether the API key is working properly. For more detailed documentation, see docs/README.md. The project uses MIT License.
