ATLAS MCP server for AI agents

ATLAS is a powerful project, knowledge, and task management system designed for LLM Agents. It implements the Model Context Protocol (MCP) to enable AI models to interact with a project management database, managing projects, tasks, and knowledge items through a structured system built on a Neo4j graph database.

Installation

Clone the repository:

git clone https://github.com/cyanheads/atlas-mcp-server.git
cd atlas-mcp-server

Install dependencies:
```
npm install
```
Configure Neo4j: Start a Neo4j instance using the provided Docker configuration:
```
docker-compose up -d
```
Update your .env file with Neo4j connection details.
Build the project:
```
npm run build
```

Running the Server

ATLAS MCP Server supports multiple transport mechanisms:

Standard I/O (stdio)

This is the default mode, typically used for direct integration with local MCP clients:

npm run start:stdio

Streamable HTTP

This mode allows the server to listen for MCP requests over HTTP:

npm run start:http

The server will listen on the host and port defined in your .env file (default: 127.0.0.1:3010).

Web UI

A basic experimental Web UI is available for viewing Project, Task, & Knowledge details:

npm run webui

Configuration

Environment Variables

Set these variables in your MCP Client configuration or in a .env file:

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password2

# Application Configuration
MCP_LOG_LEVEL=debug
LOGS_DIR=./logs
NODE_ENV=development

# MCP Transport Configuration
MCP_TRANSPORT_TYPE=stdio
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3010

MCP Client Settings

For Stdio Transport:

{
  "mcpServers": {
    "atlas-mcp-server-stdio": {
      "command": "node",
      "args": ["/full/path/to/atlas-mcp-server/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password2",
        "MCP_LOG_LEVEL": "info",
        "NODE_ENV": "development",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

For Streamable HTTP:

{
  "mcpServers": {
    "atlas-mcp-server-http": {
      "command": "node",
      "args": ["/full/path/to/atlas-mcp-server/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password2",
        "MCP_LOG_LEVEL": "info",
        "NODE_ENV": "development",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3010",
        "MCP_HTTP_HOST": "127.0.0.1"
      }
    }
  }
}

Using the Tools

ATLAS provides a suite of tools for project, task, and knowledge management:

Project Management

Creating a Project

{
  "name": "atlas_project_create",
  "input": {
    "mode": "single",
    "name": "Market Research Report",
    "description": "Comprehensive analysis of market trends for Q3 2023",
    "status": "in_progress",
    "completionRequirements": "Complete market analysis with competitor comparisons",
    "outputFormat": "PDF Report",
    "taskType": "research"
  }
}

Listing Projects

{
  "name": "atlas_project_list",
  "input": {
    "mode": "all"
  }
}

Task Management

Creating a Task

{
  "name": "atlas_task_create",
  "input": {
    "mode": "single",
    "projectId": "project-123",
    "title": "Gather Competitor Data",
    "description": "Collect pricing and feature information from top 5 competitors",
    "priority": "high",
    "status": "todo",
    "tags": ["research", "competitors"]
  }
}

Listing Tasks for a Project

{
  "name": "atlas_task_list",
  "input": {
    "projectId": "project-123"
  }
}

Knowledge Management

Adding Knowledge

{
  "name": "atlas_knowledge_add",
  "input": {
    "mode": "single",
    "projectId": "project-123",
    "text": "According to recent industry reports, the market is expected to grow by 15% in Q3 2023.",
    "domain": "market_research",
    "tags": ["industry_trend", "forecast"]
  }
}

Listing Knowledge for a Project

{
  "name": "atlas_knowledge_list",
  "input": {
    "projectId": "project-123"
  }
}

Search Operations

{
  "name": "atlas_unified_search",
  "input": {
    "value": "market research",
    "entityTypes": ["Project", "Task", "Knowledge"]
  }
}

Database Backup and Restore

Creating a Backup

npm run db:backup

This creates a timestamped directory with exported JSON files in the ./atlas-backups/ folder.

Restoring from Backup

npm run db:import ./atlas-backups/atlas-backup-20250326120000

Warning: This is a destructive operation that will overwrite all current data.

Accessing Resources

ATLAS exposes data through standard MCP resource endpoints:

atlas://projects - List all projects
atlas://tasks - List all tasks
atlas://knowledge - List all knowledge items
atlas://projects/{projectId} - Get a specific project
atlas://tasks/{taskId} - Get a specific task
atlas://projects/{projectId}/tasks - Get tasks for a specific project

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "atlas-mcp-server-stdio" '{"command":"node","args":["/full/path/to/atlas-mcp-server/dist/index.js"],"env":{"NEO4J_URI":"bolt://localhost:7687","NEO4J_USER":"neo4j","NEO4J_PASSWORD":"password2","MCP_LOG_LEVEL":"info","NODE_ENV":"development","MCP_TRANSPORT_TYPE":"stdio"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "atlas-mcp-server-stdio": {
            "command": "node",
            "args": [
                "/full/path/to/atlas-mcp-server/dist/index.js"
            ],
            "env": {
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USER": "neo4j",
                "NEO4J_PASSWORD": "password2",
                "MCP_LOG_LEVEL": "info",
                "NODE_ENV": "development",
                "MCP_TRANSPORT_TYPE": "stdio"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "atlas-mcp-server-stdio": {
            "command": "node",
            "args": [
                "/full/path/to/atlas-mcp-server/dist/index.js"
            ],
            "env": {
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USER": "neo4j",
                "NEO4J_PASSWORD": "password2",
                "MCP_LOG_LEVEL": "info",
                "NODE_ENV": "development",
                "MCP_TRANSPORT_TYPE": "stdio"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect