Graphite Atlas MCP Server

A Model Context Protocol (MCP) server that provides Claude and other AI assistants with access to your Graphite Atlas knowledge graphs.

Features

• 🗺️ Atlas Management: Create, read, update, and delete knowledge graphs
• 📍 Point Operations: Add and manage nodes (entities) in your graphs
• 🔗 Path Operations: Create and manage edges (relationships) between points
• 🧠 Brain Dump: AI-powered graph generation from text
• 🔍 Search: Find points and paths across your atlases

Installation

From npm

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

From source

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 Desktop MCP"
   • Description: "MCP server for Claude Desktop integration"
   • Click "Create App"
4. Generate a JWT token:
   • Click "Generate Token" on your new app
   • Token Name: "Claude Desktop"
   • Environment: Production (or Development for testing)
   • Scopes: Select the permissions you need (see Scopes below)
     • Recommended: Select "*" (Full Access) for easiest setup
     • Or select specific scopes like read:points, write:points, read:paths, write:paths, etc.
   • Expires In: 90 days (recommended)
   • Click "Generate Token"
5. Copy your JWT token:
   • The token will only be shown once - copy it immediately!
   • You can also copy the auto-generated Claude Desktop config snippet

2. Configure Claude Desktop

Add the MCP server to your Claude Desktop configuration:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Or if running from source:

{
  "mcpServers": {
    "graphite-atlas": {
      "command": "node",
      "args": [
        "/path/to/graphite_atlas/mcp/dist/index.js"
      ],
      "env": {
        "GRAPHITE_ACCESS_TOKEN": "your_access_token_here",
        "GRAPHITE_API_URL": "https://graphiteatlas.com"
      }
    }
  }
}

3. Restart Claude Desktop

Restart Claude Desktop to load the new MCP server.

4. Test It!

Ask Claude:

"List my Graphite Atlas knowledge graphs"

Claude should use the list_atlases tool to fetch and display your atlases.

Available Tools

Atlas Management

list_atlases

List all knowledge graphs owned by the user.

Parameters: None

Example:

"Show me all my atlases"

get_atlas

Get details of a specific atlas.

Parameters:

• atlas_id (string, required): The atlas ID

Example:

"Show me details for atlas abc-123"

create_atlas

Create a new knowledge graph.

Parameters:

• name (string, required): Atlas name
• description (string, optional): Atlas description

Example:

"Create a new atlas called 'Project Notes' for tracking my project ideas"

update_atlas

Update an atlas name or description.

Parameters:

• atlas_id (string, required): The atlas ID
• name (string, optional): New name
• description (string, optional): New description

delete_atlas

Delete an atlas permanently.

Parameters:

• atlas_id (string, required): The atlas ID

⚠️ Warning: This action cannot be undone.

Point (Node) Operations

list_points

List all points in an atlas.

Parameters:

• atlas_id (string, required): The atlas ID

Example:

"Show me all points in my Project Notes atlas"

get_point

Get details of a specific point.

Parameters:

• atlas_id (string, required): The atlas ID
• point_id (string, required): The point ID

create_point

Create a new point (entity/concept).

Parameters:

• atlas_id (string, required): The atlas ID
• name (string, required): Point name
• type (string, required): Point type (e.g., "Person", "Company", "Concept")
• properties (object, optional): Additional properties

Example:

"In my Project Notes atlas, create a new point called 'AI Integration' of type 'Feature' with property 'priority' set to 'high'"

update_point

Update a point's name, type, or properties.

Parameters:

• atlas_id (string, required): The atlas ID
• point_id (string, required): The point ID
• name (string, optional): New name
• type (string, optional): New type
• properties (object, optional): Updated properties (merged)

delete_point

Delete a point from an atlas.

Parameters:

• atlas_id (string, required): The atlas ID
• point_id (string, required): The point ID

search_points

Search for points by name or type.

Parameters:

• atlas_id (string, required): The atlas ID
• query (string, required): Search query

Example:

"Search for all points related to 'AI' in my Project Notes atlas"

Path (Relationship) Operations

list_paths

List all paths (relationships) in an atlas.

Parameters:

• atlas_id (string, required): The atlas ID

get_path

Get details of a specific path.

Parameters:

• atlas_id (string, required): The atlas ID
• path_id (string, required): The path ID

create_path

Create a new path between two points.

Parameters:

• atlas_id (string, required): The atlas ID
• name (string, required): Path name
• type (string, required): Path type (e.g., "KNOWS", "WORKS_AT", "DEPENDS_ON")
• source_id (string, required): Source point ID
• target_id (string, required): Target point ID
• properties (object, optional): Additional properties

Example:

"Create a 'DEPENDS_ON' relationship from 'AI Integration' feature to 'Database Upgrade' feature"

update_path

Update a path's name, type, or properties.

Parameters:

• atlas_id (string, required): The atlas ID
• path_id (string, required): The path ID
• name (string, optional): New name
• type (string, optional): New type
• properties (object, optional): Updated properties

delete_path

Delete a path from an atlas.

Parameters:

• atlas_id (string, required): The atlas ID
• path_id (string, required): The path ID

search_paths

Search for paths by name or type.

Parameters:

• atlas_id (string, required): The atlas ID
• query (string, required): Search query

Brain Dump (AI Graph Generation)

brain_dump

Use AI to automatically generate a knowledge graph from text.

Parameters:

• atlas_id (string, required): The atlas ID to add generated graph to
• text (string, required): Text to analyze (notes, articles, transcripts)
• process_name (string, optional): Name for this brain dump process

Example:

"Take this meeting transcript and create a knowledge graph in my Project Notes atlas:

[Meeting notes about AI project planning, stakeholders, dependencies...]
"

get_brain_dump_status

Check the status of a brain dump operation.

Parameters:

• operation_id (string, required): Operation ID from brain_dump

Example:

"Check the status of brain dump operation op-xyz-789"

JWT Scopes

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

| Scope | Required For | Description | |-------|-------------|-------------| | * | All operations | Full access to all resources (recommended for personal use) | | 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 for personal use:

* (Full Access)

Recommended minimal scopes for read-only access:

read:atlases read:points read:paths read:schema

Recommended scopes for full graph editing:

read:atlases write:atlases delete:atlases read:points write:points delete:points read:paths write:paths delete:paths read:schema use:llm

Or simply use wildcard patterns:

read:* write:* delete:*

Environment Variables

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

Development

Build

npm run build

Watch Mode

npm run watch

Development Mode (with auto-reload)

npm run dev

Linting

npm run lint

Type Checking

npm run typecheck

Troubleshooting

"GRAPHITE_ACCESS_TOKEN environment variable is required"

You need to provide a valid OAuth access token. See Quick Start for instructions on getting one.

"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
4. The Graphite Atlas API is operational

"API Error (401): Unauthorized"

Your access token may be expired. Generate a new one using the refresh token flow or by reauthorizing.

Tools not appearing in Claude Desktop

1. Check the Claude Desktop logs (Help → View Logs)
2. Verify your config file syntax is valid JSON
3. Restart Claude Desktop after config changes
4. Check that the MCP server is executable (chmod +x dist/index.js if needed)

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
• Revoke unused OAuth apps from Settings → Developer

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT

Support

• Documentation: https://docs.graphiteatlas.com
• Issues: https://github.com/graphite-atlas/mcp-server/issues
• Email: [email protected]

Built with ❤️ by the Graphite Atlas team