npm package: @graphite-atlas/mcp-server
Description: Model Context Protocol server for Graphite Atlas
Author: Graphite Atlas
Latest version: 1.4.4

# Graphite Atlas MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides Claude and other AI assistants with access to your Graphite Atlas knowledge graphs.

## Features

- 🗺️ **Atlas Management** (5 tools): Create, read, update, and delete knowledge graphs
- 📍 **Point Operations** (6 tools): Add and manage nodes (entities) in your graphs
- 🔗 **Path Operations** (6 tools): Create and manage edges (relationships) between points
- 👁️ **View Management** (10 tools): Organize points into views with folders and visibility controls
- 📦 **Batch Operations** (1 tool): Create multiple points and paths in a single atomic call
- 🧠 **Brain Dump** (2 tools): AI-powered graph generation from unstructured text
- ✅ **Validation & Ontology** (4 tools): Validate types, find duplicates, and browse the ontology
- 📊 **Analytics** (4 tools): PageRank, betweenness centrality, neighborhoods, isolated nodes
- 🧮 **MAGE Algorithms** (7 tools): Community detection, shortest path, node similarity, and more

**48 tools** across 9 categories. The server includes built-in ontology context so Claude knows what Atlas is and how to use it without needing extra prompts.

## Installation

### From npm

```bash
npm install -g @graphite-atlas/mcp-server
```

### From source

```bash
cd mcp
npm install
npm run build
```

## Quick Start

### 1. Generate a JWT Token

Before using the MCP server, you need a JWT access token from Graphite Atlas:

1. **Log in** to https://graphiteatlas.com
2. **Navigate** to Profile → API Apps tab
3. **Create** a new API app:
   - Click "New App"
   - Name: "Claude MCP"
   - Description: "MCP server for Claude integration"
   - Click "Create App"
4. **Generate a JWT token**:
   - Click "Generate Token" on your new app
   - Token Name: "Claude"
   - Environment: Production (or Development for testing)
   - Scopes: Select "*" (Full Access) for easiest setup
   - Expires In: 90 days (recommended)
   - Click "Generate Token"
5. **Copy your JWT token** — it will only be shown **once**!

### 2. Configure Your Client

#### Claude Code (CLI)

Add to `~/.claude/claude_code_config.json`:

```json
{
  "mcpServers": {
    "graphite-atlas": {
      "command": "npx",
      "args": ["@graphite-atlas/mcp-server"],
      "env": {
        "GRAPHITE_ACCESS_TOKEN": "your_token_here",
        "GRAPHITE_API_URL": "https://graphiteatlas.com"
      }
    }
  }
}
```

#### Claude Desktop

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "graphite-atlas": {
      "command": "npx",
      "args": ["@graphite-atlas/mcp-server"],
      "env": {
        "GRAPHITE_ACCESS_TOKEN": "your_token_here",
        "GRAPHITE_API_URL": "https://graphiteatlas.com"
      }
    }
  }
}
```

### 3. Restart and Test

Restart your client, then ask Claude:

```
"List my atlases"
```

Claude should use the `list_atlases` tool to fetch and display your knowledge graphs.

## Available Tools

### Atlas Management (5 tools)

| Tool | Description |
|------|-------------|
| `list_atlases` | List all knowledge graphs |
| `get_atlas` | Get details of a specific atlas |
| `create_atlas` | Create a new knowledge graph |
| `update_atlas` | Update atlas name or description |
| `delete_atlas` | Delete an atlas permanently |

### Point Operations (6 tools)

Points are nodes in the graph — people, processes, systems, outcomes, etc.

| Tool | Description |
|------|-------------|
| `list_points` | List all points in an atlas |
| `get_point` | Get a specific point by ID |
| `create_point` | Create a new point (name, type, properties) |
| `update_point` | Update a point's name, type, or properties |
| `delete_point` | Delete a point |
| `search_points` | Search points by name or type |

**Valid point types**: Person, Position, Group, Organization, Vendor, Process, Step, Review, Decision, Approval, Handoff, Task, Sequence, StepGroup, And, Or, System, Artifact, API, Equipment, Skill, Transport, Outcome, Metric, Physical Site, Date, TimeRange, Temporal, AbsoluteDate, RelativeOffset

Use `lookup_ontology` to browse types and their descriptions before creating.

### Path Operations (6 tools)

Paths are typed relationships between points.

| Tool | Description |
|------|-------------|
| `list_paths` | List all paths in an atlas |
| `get_path` | Get a specific path by ID |
| `create_path` | Create a path between two points |
| `update_path` | Update a path's type or properties |
| `delete_path` | Delete a path |
| `search_paths` | Search paths by type |

**Valid path types**: has_role, reports_to, member_of, responsible_for, assigned_to, has_skill, has_subsidiary, operates_under, has_interest, performs, has_step, followed_by, followed_by_if, creates_output, from_person, to_person, handoff_of, needs_input, uses_resource, measured_by, impacts, located_in, happens_before, happens_after, simultaneous_with, has_deadline, part_of

Use `lookup_ontology` with `paths_for_type` to see which paths are valid for a given point type.

### View Management (10 tools)

Views organize subsets of points into named collections with layout and visibility controls.

| Tool | Description |
|------|-------------|
| `list_views` | List all views in an atlas |
| `get_view` | Get view details |
| `create_view` | Create a new view |
| `update_view` | Update view settings |
| `delete_view` | Delete a view |
| `get_view_points` | Get points in a view with visibility state |
| `add_points_to_view` | Add/show points in a view |
| `remove_point_from_view` | Remove/hide a point from a view |
| `get_view_hierarchy` | Get the folder tree for views |

### Batch Operations (1 tool)

| Tool | Description |
|------|-------------|
| `batch_create` | Create multiple points and paths in one atomic call |

Batch create accepts point names (not IDs) for path source/target, resolving them automatically. Useful for building out an entire org structure or process map in one call.

### Brain Dump (2 tools)

| Tool | Description |
|------|-------------|
| `brain_dump` | Generate a knowledge graph from unstructured text using AI |
| `get_brain_dump_status` | Check the status of a brain dump operation |

Pass meeting notes, transcripts, or any narrative text and the AI will extract structured points and paths.

### Validation & Ontology (4 tools)

| Tool | Description |
|------|-------------|
| `validate_points` | Validate point types against the ontology before creation |
| `validate_paths` | Validate path types against the ontology before creation |
| `find_similar_points` | Find existing points similar to a proposed name (duplicate detection) |
| `lookup_ontology` | Browse valid types, categories, and path constraints |

#### `lookup_ontology` Query Modes

| Mode | Description |
|------|-------------|
| `point_types` | List all valid point types, optionally filtered by category |
| `path_types` | List all valid path types with source/target constraints |
| `paths_for_type` | Show all valid paths from/to a specific point type |
| `search` | Case-insensitive search across type names and descriptions |

### Analytics (4 tools)

| Tool | Description |
|------|-------------|
| `get_page_rank` | Rank nodes by influence/authority |
| `get_betweenness_centrality` | Find bridge nodes connecting communities |
| `get_node_neighborhood` | Get a node's immediate connections |
| `find_isolated_nodes` | Find disconnected nodes with no relationships |

### MAGE Graph Algorithms (7 tools)

Advanced algorithms powered by Memgraph's MAGE library.

| Tool | Description |
|------|-------------|
| `mage_pagerank` | PageRank with configurable damping factor |
| `mage_betweenness_centrality` | Betweenness centrality (normalized) |
| `mage_detect_communities` | Community detection via Leiden algorithm |
| `mage_connected_components` | Find disconnected subgraphs |
| `mage_node_similarity` | Jaccard similarity between nodes |
| `mage_shortest_path` | BFS shortest path between two nodes |
| `mage_degree_centrality` | Most connected nodes (in/out/both) |

## JWT Scopes

When generating your JWT token, select the scopes you need:

| Scope | Required For | Description |
|-------|-------------|-------------|
| `*` | All operations | Full access to all resources (recommended) |
| `read:atlases` | List/get atlases | View your knowledge graphs |
| `write:atlases` | Create/update atlases | Create and modify atlases |
| `delete:atlases` | Delete atlases | Permanently delete atlases |
| `read:points` | List/get points | View nodes in your graphs |
| `write:points` | Create/update points | Add and modify nodes |
| `delete:points` | Delete points | Remove nodes |
| `read:paths` | List/get paths | View relationships |
| `write:paths` | Create/update paths | Add and modify relationships |
| `delete:paths` | Delete paths | Remove relationships |
| `read:schema` | Get schemas | View atlas ontology schemas |
| `use:llm` | Brain dump | AI-powered graph generation |
| `use:embeddings` | Semantic search | AI-powered semantic search |

**Recommended**: `*` (Full Access)

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GRAPHITE_ACCESS_TOKEN` | JWT access token (required) | - |
| `GRAPHITE_API_URL` | Graphite Atlas API base URL | `https://graphiteatlas.com` |

## Development

```bash
npm run build        # Compile TypeScript
npm run watch        # Watch mode
npm run dev          # Dev mode with tsx
npm run lint         # ESLint
npm run typecheck    # TypeScript type check
npm test             # Run tests
```

## Troubleshooting

### "GRAPHITE_ACCESS_TOKEN environment variable is required"

You need to provide a valid JWT access token. See [Quick Start](#quick-start).

### "Failed to connect to Graphite Atlas API"

Check that:
1. Your access token is valid (not expired)
2. The API URL is correct
3. You have network connectivity

### "API Error (401): Unauthorized"

Your access token may be expired. Generate a new one from Profile → API Apps.

### Tools not appearing in Claude

1. Check client logs for errors
2. Verify your config file syntax is valid JSON
3. Restart your client after config changes

## Security

- **Never commit** your access token to version control
- **Never share** your access token publicly
- **Rotate tokens** regularly
- **Use minimal scopes** required for your use case

## License

MIT

## Support

- **Documentation**: https://docs.graphiteatlas.com
- **Issues**: https://github.com/graphiteatlas/mcp/issues

---

Built with ❤️ by the Graphite Atlas team