The atlas-mcp-server
is a comprehensive management system for LLM agents, built on a Neo4j graph database architecture. It enables:
- Project Management: Create, update, delete, and list projects with dependency handling, link management, notes, and member roles
- Task Management: Create and track tasks with lifecycle management, prioritization, and dependencies
- Knowledge Management: Add, delete, and list knowledge items with domain categorization and citation support
- Deep Research: Conduct structured research with hierarchical planning
- Search Capabilities: Perform unified searches across projects, tasks, and knowledge with flexible query options
- Database Operations: Backup, restore, and reset the Neo4j database
- Whiteboard Management: Create and manage whiteboards linked to projects
- Skill Integration: List and invoke skills with parameter passing
The system leverages Neo4j's relationship management for robust data integrity and advanced querying.
ATLAS integrates with Docker for simplified installation and running of Neo4j. Docker-compose is included in the repository for self-hosting the Neo4j database.
ATLAS uses .ENV files for configuration management, with support for creating a .env file based on the provided .env.example template.
ATLAS Skills system includes git integration, with configuration options for GitHub username and email available through environment variables.
ATLAS integrates with GitHub through the Skills system, with configuration options for GitHub username and email available through environment variables.
ATLAS uses Mermaid for diagram generation and visualization of system architecture in the documentation.
ATLAS has been completely rewritten to use Neo4j as its graph database, providing native relationship management, ACID-compliant transactions, and optimized queries for data integrity.
ATLAS can be installed via npm package management system and provides npm scripts for database backup and restore operations.
Version 1.5.4 was the last version of ATLAS that used SQLite as the database before switching to Neo4j in version 2.0.
ATLAS is built with TypeScript, utilizing its type system for more robust code organization and development experience.
ATLAS: Task Management System
ATLAS (Adaptive Task & Logic Automation System) is a project, knowledge, and task management system for LLM Agents.
Built on a three-tier architecture:
Implemented as a Model Context Protocol (MCP) server, ATLAS allows LLM agents to interact with a project management database, enabling them to manage projects, tasks, and knowledge items.
Important Version Note: Version 1.5.4 is the last version that uses SQLite as the database. Version 2.0 and onwards has been completely rewritten to use Neo4j, which requires either:
- Self-hosting using Docker (docker-compose included in repository)
- Using Neo4j AuraDB cloud service: https://neo4j.com/product/auradb/
Version 2.5.0 introduces a new 3-node system (Projects, Tasks, Knowledge) that replaces the previous structure.
Table of Contents
- Overview
- Features
- Installation
- Running the Server
- Web UI (Experimental)
- Configuration
- Project Structure
- Tools
- Resources
- Database Backup and Restore
- Examples
- License
Overview
ATLAS implements the Model Context Protocol (MCP), enabling standardized communication between LLMs and external systems through:
- Clients: Claude Desktop, IDEs, and other MCP-compatible clients
- Servers: Tools and resources for project, task, and knowledge management
- LLM Agents: AI models that leverage the server's management capabilities
System Integration
The Atlas Platform integrates these components into a cohesive system:
- Project-Task Relationship: Projects contain tasks that represent actionable steps needed to achieve project goals. Tasks inherit context from their parent project while providing granular tracking of individual work items.
- Knowledge Integration: Both projects and tasks can be enriched with knowledge items, providing team members with necessary information and context.
- Dependency Management: Both projects and tasks support dependency relationships, allowing for complex workflows with prerequisites and sequential execution requirements.
- Unified Search: The platform provides cross-entity search capabilities, allowing users to find relevant projects, tasks, or knowledge based on various criteria.
Features
Project Management
- Comprehensive Tracking: Manage project metadata, statuses, and rich content (notes, links, etc.) with built-in support for bulk operations.
- Dependency & Relationship Handling: Automatically validate and track inter-project dependencies.
Task Management
- Task Lifecycle Management: Create, track, and update tasks through their entire lifecycle.
- Prioritization & Categorization: Assign priority levels and categorize tasks with tags for better organization.
- Dependency Tracking: Establish task dependencies to create structured workflows.
Knowledge Management
- Structured Knowledge Repository: Maintain a searchable repository of project-related information.
- Domain Categorization: Organize knowledge by domain and tags for easy retrieval.
- Citation Support: Track sources and references for knowledge items.
Graph Database Integration
- Native Relationship Management: Leverage Neo4j's ACID-compliant transactions and optimized queries for robust data integrity.
- Advanced Search & Scalability: Perform property-based searches with fuzzy matching and wildcards while maintaining high performance.
Unified Search
- Cross-Entity Search: Find relevant projects, tasks, or knowledge based on content, metadata, or relationships.
- Flexible Query Options: Support for case-insensitive, fuzzy, and advanced filtering options.
Installation
- Clone the repository:
- Install dependencies:
- Configure Neo4j:
Ensure you have a Neo4j instance running and accessible. You can start one using the provided Docker configuration:Update your
.env
file with the Neo4j connection details (see Configuration). - Build the project:
Running the Server
Most MCP Clients run the server automatically, but you can also run it manually for testing or development purposes using the following commands.
ATLAS MCP Server supports multiple transport mechanisms for communication:
- Standard I/O (stdio): This is the default mode and is typically used for direct integration with local MCP clients (like IDE extensions).This uses the
MCP_TRANSPORT_TYPE=stdio
setting. - Streamable HTTP: This mode allows the server to listen for MCP requests over HTTP, suitable for remote clients or web-based integrations.This uses the
MCP_TRANSPORT_TYPE=http
setting. The server will listen on the host and port defined in your.env
file (e.g.,MCP_HTTP_HOST
andMCP_HTTP_PORT
, defaulting to127.0.0.1:3010
). Ensure your firewall allows connections if accessing remotely.
Web UI (Experimental)
A basic Web UI is available for viewing Project, Task, & Knowledge details.
- Opening the UI:
- To open the UI directly in your browser, run the following command in your terminal:
- To open the UI directly in your browser, run the following command in your terminal:
- Functionality:
- You can see an example screenshot of the Web UI here.
Configuration
Environment Variables
Environment variables should be set in the client config in your MCP Client, or in a .env
file in the project root for local development.
Refer to src/config/index.ts
for all available environment variables, their descriptions, and default values.
MCP Client Settings
How you configure your MCP client depends on the client itself and the chosen transport type. An mcp.json
file in the project root can be used by some clients (like mcp-inspector
) to define server configurations; update as needed.
For Stdio Transport (Example Configuration):
For Streamable HTTP (Example Configuration):
If your client supports connecting to an MCP server via Streamable HTTP, you provide the server's endpoint (e.g., http://localhost:3010/mcp
) in your client configuration.
Note: Always use absolute paths for args
when configuring client commands if the server is not in the client's immediate working directory. The MCP_AUTH_SECRET_KEY
in the client's env
block is illustrative; actual token handling for client-to-server communication would depend on the client's capabilities and the server's authentication mechanism (e.g., sending a JWT in an Authorization
header).
Project Structure
The codebase follows a modular structure:
Tools
ATLAS provides a comprehensive suite of tools for project, task, and knowledge management, callable via the Model Context Protocol.
Project Operations
Tool Name | Description | Key Arguments |
---|---|---|
atlas_project_create | Creates new projects (single/bulk). | mode ('single'/'bulk'), id (optional client-generated ID for single mode), project details (name , description , status , urls , completionRequirements , dependencies , outputFormat , taskType ). For bulk mode, use projects (array of project objects). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_project_list | Lists projects (all/details). | mode ('all'/'details', default: 'all'), id (for details mode), filters (status , taskType ), pagination (page , limit ), includes (includeKnowledge , includeTasks ), responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_project_update | Updates existing projects (single/bulk). | mode ('single'/'bulk'), id (for single mode), updates object. For bulk mode, use projects (array of objects, each with id and updates ). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_project_delete | Deletes projects (single/bulk). | mode ('single'/'bulk'), id (for single mode) or projectIds (array for bulk mode). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
Task Operations
Tool Name | Description | Key Arguments |
---|---|---|
atlas_task_create | Creates new tasks (single/bulk). | mode ('single'/'bulk'), id (optional client-generated ID), projectId , task details (title , description , priority , status , assignedTo , urls , tags , completionRequirements , dependencies , outputFormat , taskType ). For bulk mode, use tasks (array of task objects). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_task_update | Updates existing tasks (single/bulk). | mode ('single'/'bulk'), id (for single mode), updates object. For bulk mode, use tasks (array of objects, each with id and updates ). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_task_delete | Deletes tasks (single/bulk). | mode ('single'/'bulk'), id (for single mode) or taskIds (array for bulk mode). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_task_list | Lists tasks for a specific project. | projectId (required), filters (status , assignedTo , priority , tags , taskType ), sorting (sortBy , sortDirection ), pagination (page , limit ), responseFormat ('formatted'/'json', optional, default: 'formatted'). |
Knowledge Operations
Tool Name | Description | Key Arguments |
---|---|---|
atlas_knowledge_add | Adds new knowledge items (single/bulk). | mode ('single'/'bulk'), id (optional client-generated ID), projectId , knowledge details (text , tags , domain , citations ). For bulk mode, use knowledge (array of knowledge objects). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_knowledge_delete | Deletes knowledge items (single/bulk). | mode ('single'/'bulk'), id (for single mode) or knowledgeIds (array for bulk mode). responseFormat ('formatted'/'json', optional, default: 'formatted'). |
atlas_knowledge_list | Lists knowledge items for a specific project. | projectId (required), filters (tags , domain , search ), pagination (page , limit ), responseFormat ('formatted'/'json', optional, default: 'formatted'). |
Search Operations
Tool Name | Description | Key Arguments |
---|---|---|
atlas_unified_search | Performs unified search across entities. | value (search term, required), property (optional: if specified, performs regex search on this property; if omitted, performs full-text search), filters (entityTypes , taskType , assignedToUserId ), options (caseInsensitive (default: true, for regex), fuzzy (default: false, for regex 'contains' or full-text Lucene fuzzy)), pagination (page , limit ), responseFormat ('formatted'/'json', optional, default: 'formatted'). |
Research Operations
Tool Name | Description | Key Arguments |
---|---|---|
atlas_deep_research | Initiates a structured deep research process by creating a hierarchical plan within the Atlas knowledge base. | projectId (required), researchTopic (required), researchGoal (required), scopeDefinition (optional), subTopics (required array of objects, each with question (required), initialSearchQueries (optional array), nodeId (optional), priority (optional), assignedTo (optional), initialStatus (optional, default: 'todo')), researchDomain (optional), initialTags (optional), planNodeId (optional), createTasks (optional, default: true), responseFormat ('formatted'/'json', optional, default: 'formatted'). |
Database Operations
Tool Name | Description | Key Arguments |
---|---|---|
atlas_database_clean | Destructive: Completely resets the database, removing all projects, tasks, and knowledge. | acknowledgement (must be set to true to confirm, required), responseFormat ('formatted'/'json', optional, default: 'formatted'). |
Resources
ATLAS exposes project, task, and knowledge data through standard MCP resource endpoints.
Direct Resources
Resource Name | Description |
---|---|
atlas://projects | List of all projects in the Atlas platform with pagination support. |
atlas://tasks | List of all tasks in the Atlas platform with pagination and filtering support. |
atlas://knowledge | List of all knowledge items in the Atlas platform with pagination and filtering support. |
Resource Templates
Resource Name | Description |
---|---|
atlas://projects/{projectId} | Retrieves a single project by its unique identifier (projectId ). |
atlas://tasks/{taskId} | Retrieves a single task by its unique identifier (taskId ). |
atlas://projects/{projectId}/tasks | Retrieves all tasks belonging to a specific project (projectId ). |
atlas://knowledge/{knowledgeId} | Retrieves a single knowledge item by its unique identifier (knowledgeId ). |
atlas://projects/{projectId}/knowledge | Retrieves all knowledge items belonging to a specific project (projectId ). |
Database Backup and Restore
ATLAS provides functionality to back up and restore the Neo4j database content. The core logic resides in src/services/neo4j/backupRestoreService.ts
.
Backup Process
- Mechanism: The backup process exports all
Project
,Task
, andKnowledge
nodes, along with their relationships, into separate JSON files. Afull-export.json
containing all data is also created. - Output: Each backup creates a timestamped directory (e.g.,
atlas-backup-YYYYMMDDHHMMSS
) within the configured backup path (default:./atlas-backups/
). This directory containsprojects.json
,tasks.json
,knowledge.json
,relationships.json
, andfull-export.json
. - Manual Backup: You can trigger a manual backup using the provided script:This command executes
scripts/db-backup.ts
, which calls theexportDatabase
function.
Restore Process
- Mechanism: The restore process first completely clears the existing Neo4j database. Then, it imports nodes and relationships from the JSON files located in the specified backup directory. It prioritizes
full-export.json
if available. - Warning: Restoring from a backup is a destructive operation. It will overwrite all current data in your Neo4j database.
- Manual Restore: To restore the database from a backup directory, use the import script:Replace
<path_to_backup_directory>
with the actual path to the backup folder (e.g.,./atlas-backups/atlas-backup-20250326120000
). This command executesscripts/db-import.ts
, which calls theimportDatabase
function. - Relationship Handling: The import process attempts to recreate relationships based on the
id
properties stored within the nodes during export. Ensure your nodes have consistentid
properties for relationships to be restored correctly.
Examples
The examples/
directory contains practical examples demonstrating various features of the ATLAS MCP Server.
- Backup Example: Located in
examples/backup-example/
, this shows the structure and format of the JSON files generated by thenpm run db:backup
command. See the Examples README for more details. - Deep Research Example: Located in
examples/deep-research-example/
, this demonstrates the output and structure generated by theatlas_deep_research
tool. It includes a markdown file (covington_community_grant_research.md
) summarizing the research plan and a JSON file (full-export.json
) containing the raw data exported from the database after the research plan was created. See the Examples README for more details.
License
Apache License 2.0
You must be authenticated.
Tools
ATLAS (Adaptive Task & Logic Automation System) is a Model Context Protocol server that provides hierarchical task management capabilities to Large Language Models. This tool provides LLMs with the structure and context needed to manage complex tasks and dependencies.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables Claude and other LLMs to interact with Notion workspaces, providing capabilities like searching, retrieving, creating and updating pages, as well as managing databases.Last updated -2752TypeScript
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to access and search Atlassian Confluence content, allowing integration with your organization's knowledge base.Last updated -53198TypeScript
- -securityFlicense-qualityA Model Context Protocol server that enables integration with the TESS API, allowing users to list and manage agents, execute agents with custom messages, and manage files through natural language interfaces.Last updated -TypeScript
MongoDB MCP Serverofficial
-securityAlicense-qualityA Model Context Protocol server that enables AI assistants to interact with MongoDB Atlas resources through natural language, supporting database operations and Atlas management functions.Last updated -1,597170TypeScriptApache 2.0