# 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**