ATLAS MCP server

ATLAS is a task management system built on the Model Context Protocol (MCP), enabling LLM agents to interact with a project management database. It provides a structured way to manage projects, tasks, and knowledge items with a three-tier architecture, making it ideal for AI-assisted project coordination.

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Configure Neo4j:

   Start Neo4j using the provided Docker configuration:

   docker-compose up -d
   

   Update your .env file with Neo4j connection details.

4. Build the project:

   npm run build
   

Running the Server

ATLAS MCP Server supports multiple transport mechanisms:

Standard I/O (stdio)

npm run start:stdio

Streamable 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).

Configuration

Environment Variables

Create a .env file in the project root with the following settings:

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

# Application Configuration
LOG_LEVEL=info
NODE_ENV=development

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

# MCP Security Configuration
MCP_RATE_LIMIT_WINDOW_MS=60000
MCP_RATE_LIMIT_MAX_REQUESTS=100

# Database Backup Configuration
BACKUP_MAX_COUNT=10
BACKUP_FILE_DIR=./atlas-backups

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",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

For HTTP Transport:

{
  "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",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3010",
        "MCP_HTTP_HOST": "127.0.0.1"
      }
    }
  }
}

Using ATLAS Tools

Project Management

Creating Projects

{
  "mode": "single",
  "name": "Website Redesign",
  "description": "Modernize company website with responsive design",
  "status": "active",
  "completionRequirements": "New website deployed with all pages migrated",
  "outputFormat": "Website with documentation",
  "taskType": "development"
}

Listing Projects

{
  "mode": "all",
  "status": "active",
  "page": 1,
  "limit": 10
}

Task Management

Creating Tasks

{
  "mode": "single",
  "projectId": "project-123",
  "title": "Design Homepage Layout",
  "description": "Create modern, responsive homepage design",
  "priority": "high",
  "status": "todo",
  "assignedTo": "[email protected]",
  "tags": ["design", "homepage"],
  "completionRequirements": "Approved mockup in Figma"
}

Listing Tasks

{
  "projectId": "project-123",
  "status": "todo",
  "priority": "high",
  "page": 1,
  "limit": 10
}

Knowledge Management

Adding Knowledge

{
  "mode": "single",
  "projectId": "project-123",
  "text": "The current website uses Bootstrap 4.6 with jQuery for interactions.",
  "domain": "technical",
  "tags": ["website", "frontend"]
}

Listing Knowledge

{
  "projectId": "project-123",
  "domain": "technical",
  "page": 1,
  "limit": 10
}

Search Operations

Unified Search

{
  "value": "responsive design",
  "entityTypes": ["projects", "tasks", "knowledge"],
  "caseInsensitive": true,
  "fuzzy": true,
  "page": 1,
  "limit": 20
}

Database Backup and Restore

Manual Backup

npm run db:backup

This creates a timestamped directory with exported data in JSON format.

Restoring from Backup

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

Warning: This operation will overwrite all current data in your Neo4j database.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.