Atlan Data Catalog MCP server

The Atlan Model Context Protocol (MCP) server enables AI agents to interact with Atlan services, providing tools for searching, retrieving, traversing, and updating assets within your data catalog.

Installation Options

Prerequisites

Before installing, you'll need:

• An Atlan API key (generate one from the Atlan documentation)
• Your Atlan instance URL (https://your-instance.atlan.com)

Python-based Installation

1. Install Python 3.11 (macOS example):

# Install homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to your PATH (if not already done)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Install Python 3.11
brew install [email protected]

# Verify installation
python3 --version  # Should show Python 3.11.x

2. Install uv package manager:

# Mac
brew install uv

# Verify installation
uv --version

3. Clone and set up the repository:

# Clone the repository
git clone https://github.com/atlanhq/agent-toolkit.git
cd agent-toolkit/modelcontextprotocol

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Mac/Linux

# Install dependencies
uv sync

Docker/Podman Installation

Option 1: Docker Desktop:

• Download and install Docker Desktop
• Verify installation with docker --version and docker compose version

Option 2: Docker CLI with Colima:

# Install Colima (for Mac)
brew install colima

# Start Colima
colima start

# Install Docker CLI
brew install docker

# Verify installation
docker --version

# Build the Atlan MCP server image
git clone https://github.com/atlanhq/agent-toolkit.git
cd agent-toolkit/modelcontextprotocol
docker build . -t atlan-mcp-server:latest

Usage Instructions

Configuring with Claude Desktop

1. Open Claude Desktop
2. Go to Settings (Cmd + , or click on Claude → Settings)
3. Navigate to the Developer tab
4. Click Edit Config to open claude_desktop_config.json
5. Add the MCP configuration depending on your installation method:

For Python-based installation:

{
  "mcpServers": {
    "Atlan MCP": {
      "command": "uv",
      "args": [
        "run",
        "/path/to/your/agent-toolkit/modelcontextprotocol/.venv/bin/atlan-mcp-server"
      ],
      "env": {
        "ATLAN_API_KEY": "your_api_key",
        "ATLAN_BASE_URL": "https://your-instance.atlan.com",
        "ATLAN_AGENT_ID": "your_agent_id"
      }
    }
  }
}

For Docker-based installation:

{
  "mcpServers": {
    "atlan": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ATLAN_API_KEY=your_api_key",
        "-e",
        "ATLAN_BASE_URL=https://your-instance.atlan.com",
        "-e",
        "ATLAN_AGENT_ID=your_agent_id",
        "atlan-mcp-server:latest"
      ]
    }
  }
}

Configuring with Cursor

1. Download and install Cursor
2. Open your project in Cursor
3. Create a .cursor directory in the project root if not present
4. Create a mcp.json file inside the .cursor directory
5. Add the same MCP configuration as shown above for Claude Desktop

Available Tools

The Atlan MCP server provides these tools to interact with your data catalog:

• search_assets: Search for assets based on specific conditions
• get_assets_by_dsl: Retrieve assets using a DSL query
• traverse_lineage: Retrieve lineage for an asset
• update_assets: Update asset attributes (user description and certificate status)

Troubleshooting

If Claude shows an error like spawn uv ENOENT, it likely can't find the uv executable. To fix this:

• Make sure uv is installed and in your PATH
• Run which uv to verify the installation path
• Update Claude's configuration to point to the exact uv path using the output from whereis uv

For any additional help, contact [email protected] or create a GitHub issue.

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.