# Gcore MCP Server
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FG-Core%2Fgcore-mcp-server.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FG-Core%2Fgcore-mcp-server?ref=badge_shield)


MCP (Model Context Protocol) server for Gcore API. This server provides tools for interacting with Gcore Cloud API via LLM assistants.

## Usage

**Note:** As we have multiple resources available, providing all of them at once to most LLM clients can overwhelm the model and lead to confusion among the tools. For most clients, it is recommended to specify only the necessary resources for your task to ensure optimal performance and clarity. Some clients, like Claude Code, handle this differently — see below.

### Integration with Cursor IDE

Add the server to your Cursor IDE configuration file (`~/.cursor/mcp.json`):

```json
{
  "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": "4***1",
        "GCORE_TOOLS": "instances,management,cloud.gpu_baremetal.clusters.*"
      }
    }
  }
}
```

### Integration with Claude Code

Add the server to your Claude Code configuration file (`~/.claude.json`):

```json
{
  "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": "4***1",
        "GCORE_TOOLS": "*"
      }
    }
  }
}
```

Setting `GCORE_TOOLS=*` loads all available tools, which works well with Claude Code thanks to its **Tool Search** feature. Unlike other clients, Claude Code defers tool schema loading — tool schemas are only fetched on demand when they match a query. This means registering many tools doesn't bloat the context window.

Claude Code shows a warning when tools exceed 10% of the context window. With deferred loading, this isn't an issue even with all tools enabled.

The `uvx` command runs the server in a temporary environment without requiring a persistent installation. See [Running in a Temporary Environment](#running-in-a-temporary-environment-one-off-execution) for more details.

**Note:** You can find instructions on how to obtain a Gcore API Key [here](https://gcore.com/docs/account-settings/create-use-or-delete-a-permanent-api-token).

**Optional variables:**
- `GCORE_BASE_URL`: "https://api.gcore.com",
- `GCORE_CLOUD_PROJECT_ID`: "1",
- `GCORE_CLOUD_REGION_ID`: "76",
- `GCORE_CLIENT_ID`: "2",
- `GCORE_ALLOWED_HOSTS`: "" (HTTP transport only; loopback names always allowed)
- `GCORE_ALLOWED_ORIGINS`: "" (HTTP transport only)

### HTTP transport security

The HTTP transport (`GCORE_TRANSPORT=http`) validates the `Host` and `Origin`
headers of every request, as required by the MCP Streamable HTTP specification.
This prevents a web page the operator visits from reaching a listener bound to
loopback via DNS rebinding.

- `GCORE_ALLOWED_HOSTS` is a comma-separated list of additional host names,
  matched as glob patterns. Ports are ignored on both sides, so list host
  names only (`mcp.internal`, not `mcp.internal:8000`). The built-in names
  `127.0.0.1`, `localhost` and `::1`, plus the concrete address the listener
  is bound to, are always accepted. Any other `Host` is rejected with
  `421 Misdirected Request`.
- `GCORE_ALLOWED_ORIGINS` is a comma-separated list of additional browser
  origins, also glob-matched. On top of it FastMCP always accepts an `Origin`
  equal to the request's own origin, and any loopback origin when the `Host`
  is loopback — so another web app running on your machine is trusted, a
  DNS-rebound page on an attacker's domain is not. Any other `Origin` is
  rejected with `403`. Requests without an `Origin` header (typical for
  non-browser MCP clients) are unaffected. Known FastMCP limitation: an
  IPv6 literal origin such as `http://[::1]:3000` cannot be allow-listed,
  because the brackets are read as glob syntax.

Validation is FastMCP's host/origin guard in strict mode, which this server
turns on for the HTTP transport regardless of the bind address. Only the
`gcore-mcp-server` entry point applies this policy; loading the module's `mcp`
object through another runner (such as `fastmcp run …:mcp`) does not.

The legacy SSE transport is not supported and `GCORE_TRANSPORT=sse` refuses to
start: FastMCP does not apply this validation to its SSE app, so an SSE listener
would run without it.

The HTTP transport does **not** authenticate clients: anyone who can reach the
listener can call every enabled tool using the server's `GCORE_API_KEY`. Bind it
to loopback and do not expose it to an untrusted network.

## Configuration

### Tool Selection

The server uses a **unified configuration approach** via the `GCORE_TOOLS` environment variable. This single variable can contain a mix of predefined toolset names and custom patterns:

```bash
# Mixed toolsets and patterns
export GCORE_TOOLS="instances,management,cloud.gpu_baremetal.clusters.*,dns.records.create"

# Only toolsets
export GCORE_TOOLS="instances,management"

# Only patterns  
export GCORE_TOOLS="cloud.*,waap.*"

# Default behavior (if not set)
# Uses "management,instances" toolsets for HTTP mode, "management" for stdio
```

#### Configuration Modes

1. **Default Mode** (no configuration)
   - HTTP transport: Uses `management,instances` toolsets
   - stdio transport: Uses `management` toolset

2. **Toolset Mode** (predefined tool collections)
   - Use predefined toolset names: `instances`, `management`, `ai_ml`, etc.
   - Example: `GCORE_TOOLS="instances,management"`

3. **Pattern Mode** (custom tool filtering)
   - Use wildcard patterns to match tool names from the Gcore SDK
   - Exact matches: `cloud.instances.create`, `dns.records.delete`
   - Wildcard matches: `cloud.*`, `waap.*`, `cloud.gpu_baremetal.clusters.*`
   - Example: `GCORE_TOOLS="cloud.instances.*,waap.*"`

4. **Combined Mode** (toolsets + patterns)
   - Mix predefined toolsets with custom patterns
   - Toolset definitions have priority over pattern matches
   - Example: `GCORE_TOOLS="instances,cloud.gpu_baremetal.clusters.*"`

#### Available Toolsets

The system includes several predefined toolsets for common workflows:

- **`management`**: Core account and project management
- **`instances`**: Virtual machine operations
- **`baremetal`**: Bare metal server operations
- **`gpu_baremetal`**: GPU bare metal cluster management
- **`gpu_virtual`**: GPU virtual cluster management
- **`networking`**: Networks, Floating IPs, Load Balancers
- **`security`**: Security Groups, SSH Keys, Secrets
- **`storage`**: Volumes, File Shares
- **`ai`**: AI Clusters
- **`ai_ml`**: AI/ML inference services
- **`billing`**: Cost reports and billing information
- **`containers`**: Container registries
- **`cdn`**: CDN resources, origin groups, certificates, and cache management
- **`cleanup`**: Deletion and cleanup operations
- **`list`**: List/read-only operations

#### Pattern Syntax

Patterns support wildcard matching using `*`:

- **Exact matches**: `cloud.instances.create` matches only that specific method
- **Wildcard matches**: `cloud.instances.*` matches all instance methods
- **Broad wildcards**: `cloud.*` matches all cloud service methods
- **Service-specific**: `waap.*` matches all WAAP methods

#### Priority System

When using combined mode:
1. **Toolset tools** are included first (highest priority)
2. **Pattern-matched tools** are added second
3. **Duplicates are removed** while preserving order
4. Toolset definitions take precedence over pattern matches

#### Examples

```bash
# Development: Get specific tools for testing
export GCORE_TOOLS="cloud.instances.create,cloud.instances.delete,cloud.volumes.create"

# Full cloud management
export GCORE_TOOLS="management,instances,storage,networking"

# GPU cluster operations with custom additions  
export GCORE_TOOLS="gpu_baremetal,cloud.instances.create,waap.*"

# All services with wildcard
export GCORE_TOOLS="cloud.*,waap.*"

# Minimal setup
export GCORE_TOOLS="instances"
```

## Running in a Temporary Environment (One-off Execution)

If you want to run the server without installing it persistently (e.g., for a quick test or a single use), you can use `uvx`. This command fetches the package, runs the specified script in a temporary environment, and then discards the environment.


To run the latest version from the main branch:
```bash
uvx --from "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git" gcore-mcp-server
```

To run a specific version (e.g., `v0.1.1`):
```bash
uvx --from "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git@v0.1.1" gcore-mcp-server
```
Remember to set any required environment variables (like `GCORE_API_KEY`, `GCORE_TOOLS`, etc.) before running the command.

## Persistent Installation (Installing as a Tool)

For detailed installation instructions for `uv`, please refer to the [official `uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/).

You can install `gcore-mcp-server` as a command-line tool using `uv`. This makes the command available globally in your terminal without needing to specify the source each time.

To install the latest version from the main branch:
```bash
uv tool install "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git"
```

To install a specific version (e.g., `v0.1.0`):
```bash
uv tool install "gcore-mcp-server@git+https://github.com/G-Core/gcore-mcp-server.git@v0.1.0"
```

After installation, `uv` will make the `gcore-mcp-server` command available. If it's not immediately found, you might need to run `uv tool update-shell` or ensure `uv`'s tool bin directory is in your `PATH`.

Once installed, you can run it like any other command:
```bash
gcore-mcp-server
```

## Development

### Local Development Setup

```bash
# Clone the repository
git clone https://github.com//G-Core/gcore-mcp-server.git
cd gcore-mcp-server

# Install development dependencies
uv venv
source .venv/bin/activate
uv sync --dev
```

### Debugging and Testing

For debugging and development, it's recommended to use the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

The MCP Inspector provides a web interface to test and debug your MCP server interactively, allowing you to:
- Explore available tools and their schemas
- Test tool calls with different parameters
- View real-time communication between client and server
- Debug authentication and connection issues

To use it with your local development server:
1. Start your MCP server locally
2. Run the inspector and connect to your server
3. Use the web interface to test your tools



## License
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FG-Core%2Fgcore-mcp-server.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FG-Core%2Fgcore-mcp-server?ref=badge_large)