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

$3

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

$3

`bash
cd mcp
npm install
npm run build
`

Quick Start

$3

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

$3

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

`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:

`json
{
"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 to load the new MCP server.

$3

Ask Claude:
`
"List my Graphite Atlas knowledge graphs"
`

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

Available Tools

$3

#### 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.

$3

#### 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"
`

$3

#### 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

$3

#### 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

$3

`bash
npm run build
`

$3

`bash
npm run watch
`

$3

`bash
npm run dev
`

$3

`bash
npm run lint
`

$3

`bash
npm run typecheck
`

Troubleshooting

$3

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

$3

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

$3

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

$3

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: support@graphiteatlas.com

---

Built with ❤️ by the Graphite Atlas team