ATLAS
About
A task management system for LLM agents to manage projects, tasks, and knowledge using a Neo4j database for complex workflow automation.
Details
- Repository
- cyanheads/atlas-mcp-server
- License
- Apache-2.0
Explore
| Feature Area | Key Capabilities |
| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project Management | - Comprehensive Tracking: Manage project metadata, statuses, and rich content (notes, links, etc.) with built-in support for bulk operations.<br />- Dependency & Relationship Handling: Automatically validate and track inter-project dependencies. |
| Task Management | - Task Lifecycle Management: Create, track, and update tasks through their entire lifecycle.<br />- Prioritization & Categorization: Assign priority levels and categorize tasks with tags for better organization.<br />- Dependency Tracking: Establish task dependencies to create structured workflows. |
| Knowledge Management | - Structured Knowledge Repository: Maintain a searchable repository of project-related information.<br />- Domain Categorization: Organize knowledge by domain and tags for easy retrieval.<br />- 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.<br />- 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.<br />- Flexible Query Options: Support for case-insensitive, fuzzy, and advanced filtering options. |
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
ATLASCommand (node, npx, python, etc.)nodeArguments-
Argument 1
/full/path/to/atlas-mcp-server/dist/index.js
Environment-
NODE_ENV
development -
NEO4J_URI
bolt://localhost:7687 -
NEO4J_USER
neo4j -
MCP_LOG_LEVEL
info -
NEO4J_PASSWORD
password2 -
MCP_TRANSPORT_TYPE
stdio
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
-
Argument 1
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
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:
Ensure you have a Neo4j instance running and accessible. You can start one using the provided Docker configuration:
docker-compose up -d
Update your .env file with the Neo4j connection details (see Configuration).
4. Build the project:
npm run build
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).
npm run start:stdio
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.
npm run start:http
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 and MCP_HTTP_PORT, defaulting to 127.0.0.1:3010). Ensure your firewall allows connections if accessing remotely.
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.
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password2
MCP_LOG_LEVEL=debug # Minimum logging level. Options: emerg, alert, crit, error, warning, notice, info, debug. Default: "debug".
LOGS_DIR=./logs # Directory for log files. Default: "./logs" in project root.
NODE_ENV=development # 'development' or 'production'. Default: "development".
MCP_TRANSPORT_TYPE=stdio # 'stdio' or 'http'. Default: "stdio".
MCP_HTTP_HOST=127.0.0.1 # Host for HTTP transport. Default: "127.0.0.1".
MCP_HTTP_PORT=3010 # Port for HTTP transport. Default: 3010.
MCP_RATE_LIMIT_WINDOW_MS=60000 # Rate limit window in milliseconds. Default: 60000 (1 minute).
MCP_RATE_LIMIT_MAX_REQUESTS=100 # Max requests per window per IP for HTTP transport. Default: 100.
BACKUP_MAX_COUNT=10 # Maximum number of backup sets to keep. Default: 10.
BACKUP_FILE_DIR=./atlas-backups # Directory where backup files will be stored (relative to project root). Default: "./atlas-backups".
Refer to src/config/index.ts for all available environment variables, their descriptions, and default values.
atlas_project_create
Creates new projects (single/bulk). Parameters: 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). Parameters: 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). Parameters: 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). Parameters: mode ('single'/'bulk'), id (for single mode) or projectIds (array for bulk mode). responseFormat ('formatted'/'json', optional, default: 'formatted').
atlas_task_create
Creates new tasks (single/bulk). Parameters: 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). Parameters: 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). Parameters: 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. Parameters: projectId (required), filters (status, assignedTo, priority, tags, taskType), sorting (sortBy, sortDirection), pagination (page, limit), responseFormat ('formatted'/'json', optional, default: 'formatted').
atlas_knowledge_add
Adds new knowledge items (single/bulk). Parameters: 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). Parameters: 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. Parameters: projectId (required), filters (tags, domain, search), pagination (page, limit), responseFormat ('formatted'/'json', optional, default: 'formatted').
atlas_unified_search
Performs unified search across entities. Parameters: 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, fuzzy), pagination (page, limit), responseFormat ('formatted'/'json', optional, default: 'formatted').
atlas_deep_research
Initiates a structured deep research process by creating a hierarchical plan within the Atlas knowledge base. Parameters: 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').
atlas_database_clean
Completely resets the database, removing all projects, tasks, and knowledge. Parameters: acknowledgement (must be set to true to confirm, required), responseFormat ('formatted'/'json', optional, default: 'formatted').
ATLAS provides a comprehensive suite of tools for project, task, and knowledge management, callable via the Model Context Protocol.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"atlas": {
"env": {
"NODE_ENV": "development",
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"MCP_LOG_LEVEL": "info",
"NEO4J_PASSWORD": "password2",
"MCP_TRANSPORT_TYPE": "stdio"
},
"args": [
"/full/path/to/atlas-mcp-server/dist/index.js"
],
"command": "node"
}
}
}Linux
{
"env": {
"NODE_ENV": "development",
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"MCP_LOG_LEVEL": "info",
"NEO4J_PASSWORD": "password2",
"MCP_TRANSPORT_TYPE": "stdio"
},
"args": [
"/full/path/to/atlas-mcp-server/dist/index.js"
],
"command": "node"
}Macos
{
"env": {
"NODE_ENV": "development",
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"MCP_LOG_LEVEL": "info",
"NEO4J_PASSWORD": "password2",
"MCP_TRANSPORT_TYPE": "stdio"
},
"args": [
"/full/path/to/atlas-mcp-server/dist/index.js"
],
"command": "node"
}Windows
{
"env": {
"NODE_ENV": "development",
"NEO4J_URI": "bolt://localhost:7687",
"NEO4J_USER": "neo4j",
"MCP_LOG_LEVEL": "info",
"NEO4J_PASSWORD": "password2",
"MCP_TRANSPORT_TYPE": "stdio"
},
"args": [
"/c",
"node",
"/full/path/to/atlas-mcp-server/dist/index.js"
],
"command": "cmd"
}
[
]()
ATLAS (Adaptive Task & Logic Automation System) is a project, knowledge, and task management system for LLM Agents.
Built on a 3-node architecture:
+-------------------------------------------+
| PROJECT |
|-------------------------------------------|
| id: string |
| name: string |
| description: string |
| status: string |
| urls?: Array<{title: string, url: string}>|
| completionRequirements: string |
| outputFormat: string |
| taskType: string |
| createdAt: string |
| updatedAt: string |
+----------------+--------------------------+
| |
| |
v v
+----------------------------------+ +----------------------------------+
| TASK | | KNOWLEDGE |
|----------------------------------| |----------------------------------|
| id: string | | id: string |
| projectId: string | | projectId: string |
| title: string | | text: string |
| description: string | | tags?: string[] |
| priority: string | | domain: string |
| status: string | | citations?: string[] |
| assignedTo?: string | | createdAt: string |
| urls?: Array<{title: string, | | |
| url: string}> | | updatedAt: string |
| tags?: string[] | | |
| completionRequirements: string | | |
| outputFormat: string | | |
| taskType: string | | |
| createdAt: string | | |
| updatedAt: string | | |
+----------------------------------+ +----------------------------------+
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
| Feature Area | Key Capabilities |
| :----------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project Management | - Comprehensive Tracking: Manage project metadata, statuses, and rich content (notes, links, etc.) with built-in support for bulk operations.<br />- Dependency & Relationship Handling: Automatically validate and track inter-project dependencies. |
| Task Management | - Task Lifecycle Management: Create, track, and update tasks through their entire lifecycle.<br />- Prioritization & Categorization: Assign priority levels and categorize tasks with tags for better organization.<br />- Dependency Tracking: Establish task dependencies to create structured workflows. |
| Knowledge Management | - Structured Knowledge Repository: Maintain a searchable repository of project-related information.<br />- Domain Categorization: Organize knowledge by domain and tags for easy retrieval.<br />- 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.<br />- 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.<br />- Flexible Query Options: Support for case-insensitive, fuzzy, and advanced filtering options. |
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:
Ensure you have a Neo4j instance running and accessible. You can start one using the provided Docker configuration:
docker-compose up -d
Update your .env file with the Neo4j connection details (see Configuration).
4. Build the project:
npm run build
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).
npm run start:stdio
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.
npm run start:http
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 and MCP_HTTP_PORT, defaulting to 127.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:
npm run webui
- 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.
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
