# CalcsLive MCP Server
**Enable AI agents to perform unit-aware engineering calculations via Model Context Protocol (MCP)**
Transform AI assistants like Claude into powerful engineering calculation tools with automatic unit conversion, dependency resolution, and professional-grade accuracy.
## 🎯 What is This?
The CalcsLive MCP Server connects AI agents to [CalcsLive](https://www.calcs.live)'s calculation engine via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). This enables AI to:
- ✅ Perform complex engineering calculations with proper unit handling
- ✅ Automatically convert between unit systems (metric ↔ imperial)
- ✅ Resolve multi-step calculation dependencies
- ✅ Access 75+ unit categories with 500+ units
- ✅ Validate calculations with engineering accuracy
### Example
**User**: "Calculate hydro power for a flow rate of 150 m³/s with a head of 25 meters"
**AI (via CalcsLive MCP)**:
```json
{
"power": {
"value": 36787.5,
"unit": "kW"
}
}
```
AI automatically handles the unit-aware calculation: P = ρ × g × H × Q × η
---
## 📋 Prerequisites
1. **Node.js 18+** installed on your system
2. **CalcsLive Account** - Sign up at [calcs.live](https://www.calcs.live)
3. **MCP API Key** - Create from your [Account > API Keys](https://www.calcs.live/account/api-keys)
- Select "MCP Integration (AI Agents)" as service type
- **Free users**: Get 30-day trial (starts on first API call)
- **Premium users**: Full unlimited access
---
## 🚀 Quick Start
### 1. Install Dependencies
```bash
cd /path/to/calcslive-mcp-server
npm install
```
### 2. Build the Server
```bash
npm run build
```
### 3. Configure Claude Desktop
Edit your Claude Desktop configuration file:
**Location**:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**Add CalcsLive MCP server**:
```json
{
"mcpServers": {
"calcslive": {
"command": "node",
"args": [
"/absolute/path/to/calcslive-mcp-server/dist/index.js"
],
"env": {
"CALCSLIVE_API_KEY": "your-mcp-api-key-here",
"CALCSLIVE_API_URL": "https://www.calcs.live"
}
}
}
}
```
**Important**:
- Replace `/absolute/path/to/calcslive-mcp-server` with your actual installation path
- Replace `your-mcp-api-key-here` with your actual MCP API key from CalcsLive
### 4. Restart Claude Desktop
Quit and restart Claude Desktop to load the MCP server.
### 5. Verify Installation
In Claude Desktop, you should see the CalcsLive tools available. Try asking:
> "What CalcsLive tools do you have available?"
Claude should list `calcslive_run_script`, `calcslive_calculate`, and `calcslive_validate`.
---
## 🔧 Claude Code (VS Code Extension) Setup
If you're using Claude Code in VS Code, use the Claude CLI for easier configuration:
### 1. Install and Build
```bash
cd /path/to/calcslive-mcp-server
npm install
npm run build
```
### 2. Add MCP Server via Claude CLI
Use the `claude mcp add` command with stdio transport:
**Linux/macOS**:
```bash
claude mcp add --scope user --transport stdio calcslive node \
--env CALCSLIVE_API_KEY=your-mcp-api-key-here \
--env CALCSLIVE_API_URL=https://www.calcs.live \
-- /absolute/path/to/calcslive-mcp-server/dist/index.js
```
**Windows PowerShell**:
```powershell
claude mcp add --scope user --transport stdio calcslive node `
--env CALCSLIVE_API_KEY=your-mcp-api-key-here `
--env CALCSLIVE_API_URL=https://www.calcs.live `
-- C:\absolute\path\to\calcslive-mcp-server\dist\index.js
```
**Important Notes**:
- **`--scope user`**: Makes MCP available in **all VS Code windows** (recommended for global access)
- Without `--scope user`, MCP only works in the current project directory
- Alternative scopes: `local` (project-specific), `project` (shared in team)
- **Command structure**: `calcslive node` where `node` is the command and path comes after `--`
- Replace `/absolute/path/to/calcslive-mcp-server` (or `C:\absolute\path\to\...` on Windows) with your actual installation path
- Replace `your-mcp-api-key-here` with your actual API key from [CalcsLive API Keys](https://www.calcs.live/account/api-keys)
- For local development, use `CALCSLIVE_API_URL=http://localhost:3000`
### 3. Verify in VS Code
Restart your VS Code window or reload Claude Code extension. The CalcsLive MCP tools should now be available to Claude Code AI.
**Test it**:
> "Calculate the torque for a 2 HP motor running at 100 rpm"
Claude Code should use the `calcslive_run_script` tool to perform the calculation.
### Alternative: Manual Configuration
If Claude CLI is not available, you can manually edit the Claude Code MCP configuration file, but the CLI method is **strongly recommended** for reliability.
---
## 🛠️ Available Tools
### `calcslive_run_script` ⭐ NEW
Run stateless unit-aware calculations from Physical Quantity (PQ) script definitions. No article creation needed - fully stateless and on-the-fly.
**Example Usage**:
```
User: "Calculate the area of a circle with radius 5 cm in mm²"
AI uses: calcslive_run_script
- pqs: [
{
sym: "r",
description: "radius",
value: 5,
unit: "cm"
},
{
sym: "A",
description: "circle area",
expression: "pi * r^2",
unit: "cm²"
}
]
- outputs: {
A: { unit: "mm²" }
}
```
**Response**:
```
Calculation completed with 1 output
Results:
• circle area (A): 7853.982 mm² = pi * r^2
Detailed calculation:
{
"inputs": {
"r": { "value": 5, "unit": "cm", "baseValue": 0.05, "baseUnit": "m" }
},
"outputs": {
"A": { "value": 7853.982, "unit": "mm²", "baseValue": 0.007854, "baseUnit": "m²" }
}
}
```
**Key Features**:
- ✅ No article creation required (stateless)
- ✅ Define calculations on-the-fly with PQ JSON
- ✅ Supports Greek letters (α, β, η, ρ, etc.)
- ✅ Automatic dependency resolution
- ✅ Unit conversion for inputs and outputs
- ✅ Mathematical expressions with MathJS
### `calcslive_calculate`
Perform unit-aware calculations using existing CalcsLive articles.
**Example Usage**:
```
User: "Calculate the kinetic energy of a 1500 kg car traveling at 25 m/s"
AI uses: calcslive_calculate
- articleId: "kinetic-energy"
- inputs: {
mass: { value: 1500, unit: "kg" },
velocity: { value: 25, unit: "m/s" }
}
- outputs: {
energy: { unit: "kJ" }
}
```
**Response**:
```json
{
"energy": {
"value": 468.75,
"unit": "kJ",
"expression": "0.5 * mass * velocity^2"
}
}
```
### `calcslive_validate`
Discover available inputs/outputs for a calculation article.
**Example Usage**:
```
User: "What parameters does the hydro power calculation accept?"
AI uses: calcslive_validate
- articleId: "hydro-power"
```
**Response**:
```json
{
"articleTitle": "Hydro Power Calculation",
"inputPQs": [
{
"symbol": "Q",
"description": "Flow rate",
"unit": "m³/s",
"categoryId": "volumetric_flow_rate"
},
{
"symbol": "H",
"description": "Head",
"unit": "m",
"categoryId": "length"
}
],
"outputPQs": [
{
"symbol": "P",
"description": "Power output",
"unit": "kW",
"expression": "rho * g * H * Q * eta"
}
]
}
```
---
## 💡 Usage Examples
### Example 1: Unit Conversion
**User**: "Convert 65 mph to km/h"
**AI**: Uses CalcsLive to create a simple calculation:
```
Input: velocity = 65 mph
Output: velocity in km/h = 104.6 km/h
```
### Example 2: Multi-Step Engineering Calculation
**User**: "Calculate pump power needed for 100 gallons per minute at 50 psi with 85% efficiency"
**AI**:
1. Validates pump calculation article
2. Converts units (gpm → m³/s, psi → Pa)
3. Performs calculation with dependencies
4. Returns power in kW
### Example 3: Complex Physics Problem
**User**: "A projectile is launched at 45° with initial velocity 30 m/s. What's the maximum height?"
**AI**:
1. Uses projectile motion calculation article
2. Inputs: angle = 45°, velocity = 30 m/s
3. Calculates: max_height = (v² × sin²θ) / (2g) = 22.96 m
---
## 🔧 Development
### Build & Watch
```bash
npm run dev
```
This runs TypeScript in watch mode for development.
### Testing Locally
Run the server directly to test:
```bash
export CALCSLIVE_API_KEY=your_key_here
npm start
```
You should see:
```
CalcsLive MCP server running on stdio
API Base: https://www.calcs.live
Ready to perform unit-aware calculations for AI agents!
```
---
## 📊 API Rate Limits
| User Tier | Rate Limit | Trial Period |
|-----------|------------|--------------|
| **Free** | 60 calls/min | 30 days |
| **Premium** | 60 calls/min | N/A (unlimited) |
| **Enterprise** | Unlimited | N/A |
**Note**: Trial starts automatically on first API call. Upgrade to Premium before trial expires for continued access.
---
## 🐛 Troubleshooting
### "API key not found or inactive"
**Solution**: Check your API key in [Account > API Keys](https://www.calcs.live/account/api-keys)
- Ensure service type is "MCP Integration (AI Agents)"
- Verify key is active (not expired)
- Copy key exactly (no extra spaces)
### "Article not found"
**Solution**:
- Ensure article is set to **Public** access level
- Use the article's **Short ID**, not UUID
- Verify you own the article (can't access others' articles via API)
### "Trial has expired"
**Solution**: [Upgrade to Premium](https://www.calcs.live/pricing) to restore MCP access
### Claude Desktop Not Finding Tools
**Solution**:
1. Check config file syntax (valid JSON)
2. Verify path to `dist/index.js` is correct
3. Ensure `npm run build` completed successfully
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors
### "Unknown unit" Error
**Solution**:
- CalcsLive supports both superscript (m³) and caret (m^3) notation
- Use caret notation if typing: `m^3` instead of `m³`
- Check [Units Reference](https://www.calcs.live/help/units-reference) for valid units
---
## 🌟 Advanced Usage
### Custom API Base URL (Development)
For local development or custom deployments:
```json
{
"mcpServers": {
"calcslive": {
"env": {
"CALCSLIVE_API_URL": "http://localhost:3000",
"CALCSLIVE_API_KEY": "your-dev-key"
}
}
}
}
```
### Multiple API Keys
You can configure separate MCP servers for different projects:
```json
{
"mcpServers": {
"calcslive-project-a": {
"command": "node",
"args": ["..."],
"env": {
"CALCSLIVE_API_KEY": "project-a-key"
}
},
"calcslive-project-b": {
"command": "node",
"args": ["..."],
"env": {
"CALCSLIVE_API_KEY": "project-b-key"
}
}
}
}
```
---
## 📚 Resources
- **CalcsLive Platform**: [calcs.live](https://www.calcs.live)
- **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Units Reference**: [calcs.live/help/units-reference](https://www.calcs.live/help/units-reference)
- **API Integration Guide**: [calcs.live/help/api-integration](https://www.calcs.live/help/api-integration)
- **Create Calculations**: [calcs.live/editor/new](https://www.calcs.live/editor/new)
---
## 🤝 Support
- **Documentation**: [calcs.live/help](https://www.calcs.live/help)
- **Community**: [GitHub Discussions](https://github.com/calcslive/discussions)
- **Premium Support**: Available for Premium/Enterprise subscribers
---
## 📝 License
MIT License - See LICENSE file for details
---
## 🚀 What's Next?
1. **Create Custom Calculations**: Build your own calculation articles at [calcs.live/editor/new](https://www.calcs.live/editor/new)
2. **Explore Unit Categories**: Browse 75+ categories at [Units Reference](https://www.calcs.live/help/units-reference)
3. **Upgrade for More**: [Premium plans](https://www.calcs.live/pricing) unlock unlimited calculations
4. **Share & Collaborate**: Make calculations public for others to use via MCP
---
**Built with ❤️ for AI-powered engineering**
