# Basis MCP server

> Lets AI agents read, check, and edit Excel models by parsing workbooks, evaluating formulas, and managing interactive workbook sessions.

- Repository: https://github.com/basis1tech/basis-oss
- Page: https://hostedmcp.org/servers/basis1tech/mcp
- Transport: stdio, remote
- Stars: 0
- License: Apache-2.0
- Latest version: 0.3.2

## Install

### Claude Code

```sh
claude mcp add --env 'BASIS_API_KEY=<YOUR_BASIS_API_KEY>' mcp -- npx -y @basis1/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@basis1/mcp"
      ],
      "env": {
        "BASIS_API_KEY": "<YOUR_BASIS_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@basis1/mcp"
      ],
      "env": {
        "BASIS_API_KEY": "<YOUR_BASIS_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@basis1/mcp"],"env":{"BASIS_API_KEY":"<YOUR_BASIS_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@basis1/mcp"
      ],
      "env": {
        "BASIS_API_KEY": "<YOUR_BASIS_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp --env 'BASIS_API_KEY=<YOUR_BASIS_API_KEY>' -- npx -y @basis1/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp]
command = "npx"
args = ["-y", "@basis1/mcp"]

[mcp_servers.mcp.env]
BASIS_API_KEY = "<YOUR_BASIS_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'BASIS_API_KEY=<YOUR_BASIS_API_KEY>' mcp npx -- -y @basis1/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@basis1/mcp"
      ],
      "env": {
        "BASIS_API_KEY": "<YOUR_BASIS_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `BASIS_API_KEY` | yes | yes | Your Basis API key, from https://api.basis1.tech |
| `BASIS_BASE_URL` | no | no | Basis API base URL, to use a self-hosted server |

## Tools (22)

- `parse_workbook`
- `submit_job`
- `stream_job`
- `diff_workbooks`
- `evaluate_formula`
- `recalc_workbook`
- `create_session`
- `set_inputs`
- `get_outputs`
- `define_variable`
- `delete_variable`
- `add_sheet`
- `rename_sheet`
- `delete_sheet`
- `set_calc_settings`
- `inspect_model`
- `get_formula_range`
- `trace_dependencies`
- `audit_workbook`
- `export_workbook`
- `save_to_library`
- `list_library_files`

## FAQ

### What can the Basis MCP server do with Excel files?

It allows AI agents to parse workbooks, evaluate formulas (supporting 278 Excel functions), trace dependencies, and manage interactive sessions to change inputs and read results.

### Do I need an API key to use Basis?

Yes, you need a Basis API key to run the tools, which you can create in your account settings at basis1.tech.

### How are my local files handled?

The server reads the file from the path you provide and uploads its contents to the Basis API for processing; it does not read anything else on your computer.