GitLab Orbit Local MCP server

With the GitLab Orbit Local Model Context Protocol (MCP) server, you can securely connect AI tools and applications to your local graph. AI assistants like Claude Code, Codex, Cursor, and OpenCode can then access your graph and write SQL queries against it.

The GitLab Orbit Local MCP server is stateless. This means the server has the following characteristics:

• It queries your local graph, not a GitLab instance.
• It does not cache results or persist query history.
• It can respond to multiple clients independently.

Prerequisites

• Install either of the following tools:
  • The GitLab Orbit CLI (orbit)
  • The GitLab CLI (glab orbit)

Connect a client to the GitLab Orbit Local MCP server

The GitLab Orbit Local MCP server supports stdio transport. Arguments and commands vary depending on the MCP client and your local environment.

Connect Claude Code

Claude Code stores the MCP server configuration in one of three scopes. Choose the scope that matches your use case.

To add the MCP server for the current project, run:

claude mcp add orbit-local -- orbit mcp serve

claude mcp add orbit-local -- glab orbit local mcp serve

To add the server for all of your projects, run:

claude mcp add orbit-local --scope user -- orbit mcp serve

claude mcp add orbit-local --scope user -- glab orbit local mcp serve

To add the server for everyone who checks out the repository, run:

claude mcp add orbit-local --scope project -- orbit mcp serve

claude mcp add orbit-local --scope project -- glab orbit local mcp serve

You can also edit the .mcp.json file directly:

{
  "mcpServers": {
    "orbit-local": {
      "command": "orbit",
      "args": ["mcp", "serve"]
    }
  }
}

{
  "mcpServers": {
    "orbit-local": {
      "command": "glab",
      "args": ["orbit", "local", "mcp", "serve"]
    }
  }
}

To confirm the MCP server is connected, run:

claude mcp list

After you connect, set up your AI assistant.

Connect Codex

Codex stores the MCP server configuration in ~/.codex/config.toml. Codex always configures the server for all of your projects.

To connect to Codex, run:

codex mcp add orbit-local -- orbit mcp serve

codex mcp add orbit-local -- glab orbit local mcp serve

To confirm the server is registered, run:

codex mcp list

After you connect, set up your AI assistant.

Connect Cursor

Cursor reads the MCP server configuration from an mcp.json file. Choose the scope that matches how widely you want the server available.

To connect to Cursor, create or edit the mcp.json file for the scope you want:

{
  "mcpServers": {
    "orbit-local": {
      "type": "stdio",
      "command": "orbit",
      "args": ["mcp", "serve"]
    }
  }
}

{
  "mcpServers": {
    "orbit-local": {
      "type": "stdio",
      "command": "glab",
      "args": ["orbit", "local", "mcp", "serve"]
    }
  }
}

To confirm the server is connected, run:

agent mcp list

Connect OpenCode

Add the MCP server configuration to opencode.json in the repository root, or to ~/.config/opencode/opencode.json to use it in all of your projects:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "orbit-local": {
      "type": "local",
      "command": ["orbit", "mcp", "serve"]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "orbit-local": {
      "type": "local",
      "command": ["glab", "orbit", "local", "mcp", "serve"]
    }
  }
}

To confirm the server is connected, run:

opencode mcp list

After you connect, set up your AI assistant.

Connect other MCP clients

The GitLab Orbit Local MCP server does not expose a connection URL. Clients that require a URL cannot connect to it.

{
  "mcpServers": {
    "orbit-local": {
      "command": "orbit",
      "args": ["mcp", "serve"]
    }
  }
}

{
  "mcpServers": {
    "orbit-local": {
      "command": "glab",
      "args": ["orbit", "local", "mcp", "serve"]
    }
  }
}

To confirm the server is connected, check that your client lists the run_sql, get_graph_schema, and index tools.

MCP tools

The GitLab Orbit Local MCP server provides a set of tools that interact with your local graph.

index

Indexes a repository, or a directory of repositories, into the local graph.

Example:

Index my checked out project.

get_graph_schema

Fetches the schema. Includes table names, columns, and data types present in the local graph.

Example:

Use the `get_graph_schema` tool to show me what tables are in my local graph.

run_sql

Executes read-only SQL against the local graph. Takes an array of statements and returns one JSON row array per statement, at the same index.

A single run_sql call returns about 1 MB at most, counting all statements in the call together. Larger results fail, and the agent retries with a narrower query. If the agent does not recover, ask it for fewer results.

Example:

Show me the most used imports in this repository.