# constellation

An MCP server that hands your AI assistant the structure, dependencies and relationships inside a codebase. Raw source files stay where they are.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 3
- Author: ShiftinBits
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ShiftinBits/constellation-mcp
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/constellation

## What it does

Constellation parses your project locally. A CLI tool walks the code and pulls out structural metadata: functions, classes, variables, imports, calls and references. Only that metadata goes out; the files themselves never leave your machine. The assistant then queries a knowledge graph through the MCP server and gets answers about how the project is put together.

Each git branch keeps its own set of intelligence, so switching branches does not blur the picture. Every request is authenticated, which means `CONSTELLATION_ACCESS_KEY` is not optional — the server will not start without it.

Setup is one command per platform. On Claude: `claude mcp add constellation -e CONSTELLATION_ACCESS_KEY=<CONSTELLATION_ACCESS_KEY> -- npx -y @constellationdev/mcp`. You need Node.js v24+ and TypeScript v5.9+ if you plan to build around it. The AGPL-3.0 license matters if you intend to fold the server into a closed-source product.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `CONSTELLATION_ACCESS_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add constellation -e CONSTELLATION_ACCESS_KEY=<CONSTELLATION_ACCESS_KEY> -- npx -y @constellationdev/mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add constellation --env CONSTELLATION_ACCESS_KEY=<CONSTELLATION_ACCESS_KEY> -- npx -y @constellationdev/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "constellation": {
            "command": "npx",
            "args": [
                "-y",
                "@constellationdev/mcp"
            ],
            "env": {
                "CONSTELLATION_ACCESS_KEY": "<CONSTELLATION_ACCESS_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "constellation": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@constellationdev/mcp"
            ],
            "env": {
                "CONSTELLATION_ACCESS_KEY": "<CONSTELLATION_ACCESS_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CONSTELLATION_ACCESS_KEY=<CONSTELLATION_ACCESS_KEY> constellation npx -y @constellationdev/mcp
```
Replace <…> with your own values

## When to use it
- find every call site of a given function
- get oriented in an unfamiliar repo before the first edit
- trace dependencies between modules without reading all the code
- check what shifted in the structure after a branch switch

## Example prompts
- Show me which functions call `parseConfig` and from where.
- Which modules depend on `auth` on this branch?
- Find every class that extends `BaseHandler`.

## Similar
- [kg-extract](https://affpapa.org/en/nevibecode/skills/kg-extract.md) — skill · 730 installs
- [perspectival-constellation](https://affpapa.org/en/nevibecode/skills/perspectival-constellation.md) — skill · 389 installs
- [TokenSave](https://affpapa.org/en/nevibecode/mcp/tokensave.md) — MCP server · ★ 679
- [ckb](https://affpapa.org/en/nevibecode/mcp/ckb.md) — MCP server · ★ 111
- [agent-lsp](https://affpapa.org/en/nevibecode/mcp/agent-lsp.md) — MCP server · ★ 165
- [Synaptic Code Intelligence](https://affpapa.org/en/nevibecode/mcp/synaptic-code-intelligence.md) — MCP server · ★ 31

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md