# Atlas Mcp Server > A Model Context Protocol (MCP) server for ATLAS, a Neo4j-powered task management system for LLM Agents - implementing a three-tier architecture (Projects, Tasks, Knowledge) to manage complex workflows. Now with Deep Research. - **Type:** MCP server - **Install:** `agentstack add mcp-cyanheads-atlas-mcp-server` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [cyanheads](https://agentstack.voostack.com/s/cyanheads) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [cyanheads](https://github.com/cyanheads) - **Source:** https://github.com/cyanheads/atlas-mcp-server - **Website:** https://www.npmjs.com/package/atlas-mcp-server ## Install ```sh agentstack add mcp-cyanheads-atlas-mcp-server ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # ATLAS: Task Management System [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://github.com/cyanheads/atlas-mcp-server/releases) [](https://opensource.org/licenses/Apache-2.0) []() [](https://github.com/cyanheads/atlas-mcp-server) 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| | 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 | | 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](https://github.com/cyanheads/atlas-mcp-server/releases/tag/v1.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](#overview) - [Features](#features) - [Installation](#installation) - [Running the Server](#running-the-server) - [Web UI (Experimental)](#web-ui-experimental) - [Configuration](#configuration) - [Project Structure](#project-structure) - [Tools](#tools) - [Resources](#resources) - [Database Backup and Restore](#database-backup-and-restore) - [Examples](#examples) - [License](#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.- 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 1. **Clone the repository:** ```bash git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Configure Neo4j:** Ensure you have a Neo4j instance running and accessible. You can start one using the provided Docker configuration: ```bash docker-compose up -d ``` Update your `.env` file with the Neo4j connection details (see [Configuration](#configuration)). 4. **Build the project:** ```bash 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). ```bash 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. ```bash 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: ```bash npm run webui ``` - **Functionality**: - You can see an example screenshot of the Web UI [here](./examples/webui-example.png). ## 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 # Neo4j Configuration NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=password2 # Application Configuration 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 Configuration 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_ALLOWED_ORIGINS=http://localhost:someport,https://your-client.com # Optional: Comma-separated list of allowed origins for HTTP CORS. # MCP Security Configuration # MCP_AUTH_SECRET_KEY=your_very_long_and_secure_secret_key_min_32_chars # Optional: Secret key (min 32 chars) for JWT authentication if HTTP transport is used. CRITICAL for production. *Note: Production environment use has not been tested yet.* 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. # Database Backup Configuration 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. ### 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):** ```json { "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 (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. ```json { "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" // "MCP_AUTH_SECRET_KEY": "your-secure-token" // If authentication is enabled on the server } } } } ``` **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: ``` src/ ├── config/ # Configuration management (index.ts) ├── index.ts # Main server entry point ├── mcp/ # MCP server implementation (server.ts) │ ├── resources/ # MCP resource handlers (index.ts, types.ts, knowledge/, projects/, tasks/) │ └── tools/ # MCP tool handlers (individual tool directories) ├── services/ # Core application services │ └── neo4j/ # Neo4j database services (index.ts, driver.ts, backupRestoreService.ts, etc.) ├── types/ # Shared TypeScript type definitions (errors.ts, mcp.ts, tool.ts) └── utils/ # Utility functions and internal services (e.g., logger, errorHandler, sanitization) ``` ## 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'). … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [cyanheads](https://github.com/cyanheads) - **Source:** [cyanheads/atlas-mcp-server](https://github.com/cyanheads/atlas-mcp-server) - **License:** Apache-2.0 - **Homepage:** https://www.npmjs.com/package/atlas-mcp-server Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-cyanheads-atlas-mcp-server - Seller: https://agentstack.voostack.com/s/cyanheads - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.