atlas

ATLAS is an MCP server that provides a centralized interface for managing projects, tasks, and knowledge items via a Neo4j-backed graph database. It exposes standard MCP endpoints that LLM agents and MCP clients can call to create, read, update, and relate projects, tasks, and knowledge entries. The system is built around a 3-node architecture (Projects, Tasks, Knowledge) and supports dependencies, cross-entity search, and rich metadata like tags, citations, and URLs. With Neo4j as the backend (since v2.0+), you can deploy ATLAS using Docker (docker-compose is included) or connect to a Neo4j AuraDB instance for cloud hosting. This enables scalable graph-based queries and reliable ACID transactions for model-driven workflows.

Prerequisites:

• Docker and Docker Compose installed on your host
• Access to a Neo4j instance (local via Docker, or a Neo4j AuraDB account)

Install and run (docker-based deployment):

1. Clone the Atlas MCP server repository: git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server

2. Prepare environment variables (Neo4j connection details):

   • If using a local Neo4j instance, set NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD accordingly.
   • If using AuraDB, set NEO4J_URI to your Aura endpoint and NEO4J_USER/NEO4J_PASSWORD as required. Note: The repository includes a docker-compose setup; you may also adapt the env vars in the compose file or an .env file.

3. Start the services using Docker Compose (recommended): docker-compose up -d

4. Verify the server is reachable via MCP client endpoints provided by the repo. If you prefer a direct run, you can use the single-container approach shown below (not recommended for production): docker run -d -e NEO4J_URI="$NEO4J_URI" -e NEO4J_USER="$NEO4J_USER" -e NEO4J_PASSWORD="$NEO4J_PASSWORD" cyanheads/atlas-mcp-server

5. If you made changes or need to rebuild, reinstall dependencies and rebuild the container as needed per your environment.

Additional notes:

• Ensure your Neo4j instance is accessible from the host running Docker and that the credentials are correct.
• For production, prefer the docker-compose setup provided in the repository to manage the 3-node structure and any required services.
• Check compatibility between the Atlas MCP server version and your Neo4j version (Neo4j 4.x/5.x is typical with v2.x deployments).

Tips and common issues:

• Connection issues to Neo4j: verify NEO4J_URI is reachable (tcp/bolt). Ensure firewall and network settings allow access.
• If you upgrade Neo4j, verify compatibility with Atlas v2.x – some schema migrations may be required.
• Use the included 3-node structure (Projects, Tasks, Knowledge) for organized schema and efficient querying.
• When running behind a proxy, ensure your MCP endpoints are accessible from clients and that any proxy config allows WebSocket or MCP traffic as needed.
• If you need to customize the server behavior, review the MCP protocol documentation and the repository’s tooling for client libraries.