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. This MCP server integrates with the Climatiq API to provide carbon emission calculations for AI assistants: - set-api-key: Configure the Climatiq API key used for authentication - electricity-emis
Add this skill
npx mdskills install jagan-shanmugam/climatiq-mcp-serverComprehensive MCP server with well-documented carbon emission calculation tools and clear setup instructions
1# Climatiq MCP Server2[](https://opensource.org/licenses/MIT) 34A 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.56## Demo789https://github.com/user-attachments/assets/c253d6d1-ccf6-4c14-965e-6023ba2a029610111213https://github.com/user-attachments/assets/d61c1181-acf6-4d9f-9a48-537fc64ac4c314151617## Features1819This MCP server integrates with the Climatiq API to provide carbon emission calculations for AI assistants:2021### Tools2223- **set-api-key**: Configure the Climatiq API key used for authentication24- **electricity-emission**: Calculate carbon emissions from electricity consumption25- **travel-emission**: Calculate carbon emissions from travel by car, plane, or train26- **search-emission-factors**: Search for specific emission factors in the Climatiq database27- **custom-emission-calculation**: Perform custom calculations using specific emission factors28- **cloud-computing-emission**: Calculate emissions from cloud computing resources usage29- **freight-emission**: Calculate emissions from freight transportation30- **procurement-emission**: Calculate emissions from procurement spending31- **hotel-emission**: Calculate emissions from hotel stays32- **travel-spend**: Calculate emissions from travel expenses3334### Resources3536- Carbon calculation results are exposed as resources with a `climatiq://calculation/{id}` URI scheme37- Each resource contains detailed information about an emission factor and calculation results3839### Prompts4041- **climate-impact-explanation**: Generate natural language explanations about the climate impact of specific emission calculations4243## Installation4445### From Source4647This project uses `uv` for virtual environment and dependency management. Make sure to [install uv](https://github.com/astral-sh/uv) first.4849```bash50# Clone the repository51git clone https://github.com/your-org/climatiq-mcp-server.git52cd climatiq-mcp-server5354# Create a virtual environment55uv venv5657# Activate the virtual environment58# On macOS/Linux:59source .venv/bin/activate60# On Windows:61.venv\Scripts\activate6263# Install dependencies with development extras64uv sync --dev --extra all65```6667### Using uv6869```bash70uv pip install climatiq-mcp-server71```7273## API Key Configuration7475The server requires a Climatiq API key to function. You have several options to provide it:76771. **Environment Variable**: Set the `CLIMATIQ_API_KEY` environment variable before starting the server78 ```bash79 export CLIMATIQ_API_KEY=your_climatiq_api_key80 ```81822. **Configuration During Installation**:83 ```bash84 CLIMATIQ_API_KEY=your_climatiq_api_key uv pip install climatiq-mcp-server85 ```86873. **set-api-key Tool**: Use the `set-api-key` tool to configure it during runtime within the AI assistant88894. **Configuration File**: Create a `.env` file in the project directory:90 ```91 CLIMATIQ_API_KEY=your_climatiq_api_key92 ```9394To get a Climatiq API key:951. Sign up at [app.climatiq.io](https://app.climatiq.io/api/signup)962. Follow the instructions at [Getting API Keys](https://www.climatiq.io/docs/guides/how-tos/getting-api-key)9798## Running the Server99100The server can be started directly from the command line:101102```bash103climatiq-mcp-server104```105106## Setup in AI Assistants107108### Claude Desktop109110On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`111On Windows: `%APPDATA%/Claude/claude_desktop_config.json`112113<details>114 <summary>Configuration Example</summary>115116 ```json117 "mcpServers": {118 "climatiq-mcp-server": {119 "command": "climatiq-mcp-server",120 "env": {121 "CLIMATIQ_API_KEY": "your_climatiq_api_key"122 }123 }124 }125 ```126</details>127128## Examples and Utilities129130### Examples Directory131132The `examples/` directory contains:133134- **climatiq.ipynb**: A Jupyter notebook demonstrating direct API usage with Climatiq135- **simple_test.py**: A simple utility for testing the API integration directly without MCP protocol136137```bash138# Run the simple test139python examples/simple_test.py140```141142### Utility Scripts143144The `utils/` directory contains several helpful scripts:145146#### Test Client147148The `test_client.py` script tests all the tools, prompts, and resources:149150```bash151python utils/test_client.py152```153154#### LLM Example Client155156The `llm_example_client.py` script demonstrates how a Large Language Model (like Claude) could interact with the Climatiq MCP server:157158```bash159python utils/llm_example_client.py160```161162Key features:163- Complete API wrapper with error handling and timeout management164- Resource and result caching to preserve calculation history165- Example prompts showing how to generate natural language explanations166- Demonstrates electricity emission, travel emission, and emission factor search capabilities167168#### CLI Tool169170A command-line interface tool for direct API access without the MCP server complexity:171172```bash173# For electricity emissions174python utils/climatiq_cli.py electricity --energy 1000 --unit kWh --region US175176# For travel emissions177python utils/climatiq_cli.py travel --mode car --distance 100 --unit km --region US178```179180#### Run MCP Server Script181182Use the `run_mcp_server.py` script to directly run the server without installing:183184```bash185python utils/run_mcp_server.py186```187188## Key Concepts189190### Activity IDs191192An Activity ID is a key concept in Climatiq's API that groups similar emission factors together:193194- Each emission factor in the Climatiq database has an activity ID195- Activity IDs group emission factors describing the same activity across regions, years, sources, etc.196- Examples: `electricity-supply_grid-source_residual_mix` (electricity), `passenger_vehicle-vehicle_type_car` (car travel)197198### Calculation Methods199200The Climatiq MCP server supports multiple calculation methods:2012021. **Distance-based method** for travel emissions2032. **Advanced travel calculations** with origin-destination pairs2043. **Spend-based method** for when you only have expenditure data2054. **Direct calculations** using specific emission factors206207## Troubleshooting208209### API Key Issues2102111. Ensure `CLIMATIQ_API_KEY` is set correctly in your environment or .env file2122. Verify the API key is active in your Climatiq dashboard2133. Use `examples/simple_test.py` to check if your API key works correctly214215216## Advanced Usage217218For detailed documentation on using specific tools and advanced features, see the [docs/README.md](docs/README.md) file.219220## About Climatiq221222Climatiq 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.223224For more information about Climatiq, visit [climatiq.io](https://www.climatiq.io/).225226227## License228This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Full transparency — inspect the skill content before installing.