> ## Documentation Index
> Fetch the complete documentation index at: https://gcore.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and configure Gcore MCP Server

Prerequisites and server installation common to all AI clients. For client-specific configuration, see [Connect Claude Code](/developer-tools/mcp-server/connect-claude-code-to-gcore-mcp-server) or [Connect Cursor IDE](/developer-tools/mcp-server/connect-cursor-to-gcore-mcp-server).

## Prerequisites

**Install uv**

Gcore MCP Server runs via `uvx`, which is part of the `uv` package manager.

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    ```

    After installation, restart the terminal to update PATH.
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
uv --version
```

**Create a Gcore API token**

Create an [API token](/account-settings/api-tokens) with permissions matching the products to be used. See [API token permissions](/developer-tools/mcp-server/gcore-mcp-server-overview#api-token-permissions) for required roles per product.

<Warning>
  The API token is displayed once and cannot be retrieved later. Store it securely and do not commit it to version control.
</Warning>

## Install the server

<Tabs>
  <Tab title="Temporary (uvx)">
    `uvx` runs the server in a temporary environment without installing it permanently. The AI client handles this automatically using the `uvx` command in its configuration—no manual step is needed.

    To verify the server starts correctly, run it directly:

    ```bash theme={null}
    uvx --from "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git" gcore-mcp-server
    ```

    Pin a specific version by appending the tag:

    ```bash theme={null}
    uvx --from "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git@v0.1.1" gcore-mcp-server
    ```

    <Info>
      If the AI client shows "Failed to connect to MCP server", verify that `uv` is installed (`uv --version`) and test the `uvx` command directly from the terminal. A missing comma or bracket in the config file also prevents loading.
    </Info>
  </Tab>

  <Tab title="Persistent (uv tool)">
    Install as a global command available system-wide:

    ```bash theme={null}
    uv tool install "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git"
    ```

    If `gcore-mcp-server` is not found after installation, run `uv tool update-shell` or add the `uv` tool bin directory to `PATH`.

    Use `gcore-mcp-server` as the command in the AI client configuration instead of the `uvx` command.
  </Tab>
</Tabs>

## Environment variables

| Variable                 | Required | Description                                           |
| ------------------------ | -------- | ----------------------------------------------------- |
| `GCORE_API_KEY`          | Yes      | API token for authentication                          |
| `GCORE_TOOLS`            | No       | Tool filter pattern — controls which tools are loaded |
| `GCORE_CLOUD_PROJECT_ID` | No       | Default project ID for Cloud operations               |
| `GCORE_CLOUD_REGION_ID`  | No       | Default region ID for Cloud operations                |

<Info>
  Requests that return "401 Unauthorized" indicate an invalid or expired API token. Verify the token in the [Gcore Customer Portal](/account-settings/api-tokens) and check that it has permissions for the requested product.
</Info>

## Configure Cloud defaults

Cloud tools require `project_id` and `region_id` for most operations. Setting defaults avoids specifying them in every request.

To find project and region IDs, ask the AI client:

```
List my Cloud projects
```

```
List available Cloud regions
```

Or navigate to **Cloud** > **Projects** in the [Gcore Customer Portal](https://portal.gcore.com) and check the URL for region IDs.

Once the IDs are known, add them to the `env` section of the AI client configuration:

```json theme={null}
{
  "mcpServers": {
    "gcore-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git",
        "gcore-mcp-server"
      ],
      "env": {
        "GCORE_API_KEY": "your-api-key",
        "GCORE_TOOLS": "cloud.*",
        "GCORE_CLOUD_PROJECT_ID": "1186668",
        "GCORE_CLOUD_REGION_ID": "76"
      }
    }
  }
}
```

With defaults set, requests like "Create a VM with 2 vCPUs" use the specified project and region automatically.

<Info>
  If Cloud requests return errors about a missing project or region, add `GCORE_CLOUD_PROJECT_ID` and `GCORE_CLOUD_REGION_ID` to the `env` section, or specify them inline: "List VMs in project 1186668, region Luxembourg". Requests that return "429 Too Many Requests" indicate rate limiting—wait 60 seconds before retrying.
</Info>