README - Mage.ai MCP Integration by khushibaby

Mage.ai MCP Integration

A comprehensive Model Context Protocol (MCP) integration for Mage.ai, allowing AI assistants like Anthropic's Claude to efficiently work with Mage data pipelines.

Features

Browse Pipelines: Explore all Mage.ai pipelines and their components
View and Edit Code: Read and modify block code
Execute Pipelines: Run entire pipelines or individual blocks
Search Functionality: Find blocks by name, type, or content
Pipeline Creation: Create new pipelines and blocks from scratch

Installation

# Clone the repository
git clone https://github.com/yourusername/mage-mcp.git
cd mage-mcp

# Install dependencies
pip install -r requirements.txt

Configuration

The server can be configured using environment variables or command-line arguments:

MAGE_API_URL: URL for the Mage.ai API (default: http://localhost:6789/api/)
MAGE_API_KEY: API key for authentication (if required)

Create a .env file for persistent configuration:

MAGE_API_URL=http://localhost:6789/api/
MAGE_API_KEY=your_api_key_if_needed

Usage

Running the Server

Use the provided script to start the MCP server:

# Using stdio transport (default)
python run_server.py

# Using SSE transport
python run_server.py --transport sse --host localhost --port 3000

# Additional options
python run_server.py --api-url http://your-mage-instance:6789/api/ --api-key your_key --debug

Installing with Claude Desktop

For the best experience, install this server directly with Claude Desktop:

# Using mcp CLI
mcp install run_server.py --name "Mage.ai Manager"

# With environment variables
mcp install run_server.py -v MAGE_API_URL=http://localhost:6789/api/ -v MAGE_API_KEY=your_key

Development Mode

For testing and development:

mcp dev run_server.py

MCP Resources and Tools

Resources

mage://pipelines - List all pipelines
mage://pipelines/{pipeline_uuid} - Get pipeline details
mage://pipelines/{pipeline_uuid}/blocks - List blocks in a pipeline
mage://pipelines/{pipeline_uuid}/blocks/{block_uuid} - Get block details
mage://pipelines/{pipeline_uuid}/blocks/{block_uuid}/content - Get block code
mage://pipelines/{pipeline_uuid}/content - Get entire pipeline content
mage://pipelines/{pipeline_uuid}/execution - Get pipeline execution details
mage://blocks/search/{query} - Search blocks by name, type or content

Tools

list_all_pipelines() - List all pipelines with details
get_pipeline_details(pipeline_uuid) - Get pipeline information
list_pipeline_blocks(pipeline_uuid) - List blocks in a pipeline
get_block_content(pipeline_uuid, block_uuid) - Get block code
create_pipeline(name, description, pipeline_type) - Create a new pipeline
create_block(pipeline_uuid, name, block_type, language, content, upstream_blocks) - Create a block
update_block_content(pipeline_uuid, block_uuid, content) - Update block code
execute_pipeline(pipeline_uuid) - Run a pipeline
execute_block(pipeline_uuid, block_uuid) - Run a specific block
get_pipeline_code(pipeline_uuid) - Get complete pipeline code

Example Interactions

User: Show me all the pipelines in Mage.ai.
Claude: Let me check what pipelines are available in your Mage.ai instance.

[Lists all pipelines with descriptions and types]

User: Can you show me the blocks in the data_ingestion pipeline?
Claude: Here are all the blocks in the data_ingestion pipeline:

[Lists all blocks with their types, languages, and status]

User: I need to modify the 'transform_data' block to fix a bug.
Claude: Let me help you with that. First, let's look at the current code:

[Shows the current block code]

Here's how we can fix the bug:
[Explains the issue and suggests changes]

Would you like me to update the block with these changes?

User: Yes, please update it.
Claude: I've updated the block. Here's the new content:

[Shows the updated code]

The changes have been saved successfully.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.