uiqkos/llamacloud-rag-mcp

🦙 LlamaCloud RAG MCP Server

Professional Model Context Protocol (MCP) server for Retrieval-Augmented Generation using LlamaCloud API. Built with TypeScript following industry best practices from the Cursor MCP Integration Guide 2025.

Transform your Cursor IDE into an AI powerhouse! Connect any LlamaCloud document index and get intelligent answers with sources directly in your development workflow.

✨ Features

• 🚀 Professional TypeScript Implementation: Type-safe, compiled, production-ready
• 🦙 LlamaCloud Integration: Direct API connection to cloud-hosted document indices
• 🛠️ Three Powerful Tools: Query, search, and inspect your knowledge base
• 📋 MCP Protocol Compliant: Full compatibility with Cursor IDE
• ⚡ Performance Optimized: Efficient API calls and response handling
• 🔐 Secure: Environment-based API key management
• 📦 Easy Installation: Automated setup script included

🎯 Quick Start

Option 1: Automated Installation (Recommended)

# Clone the repository
git clone https://github.com/uiqkos/llamacloud-rag-mcp.git
cd llamacloud-rag-mcp

# Run the interactive installer
chmod +x install.sh
./install.sh

The installer will:

• ✅ Check Node.js version
• 📦 Install dependencies
• 🔧 Build the project
• 🔑 Setup your API key + Organization ID + Pipeline ID
• 📂 Configure Cursor MCP
• 🧪 Test the connection

Option 2: Manual Installation

# 1. Clone and setup
git clone https://github.com/uiqkos/llamacloud-rag-mcp.git
cd llamacloud-rag-mcp
npm install
npm run build

# 2. Get your LlamaCloud API key
# Visit: https://cloud.llamaindex.ai/

# 3. Configure Cursor
# Add to ~/.cursor/mcp.json or .cursor/mcp.json:
{
  "mcpServers": {
    "llamacloud-rag": {
      "command": "node",
      "args": ["/absolute/path/to/llamacloud-rag-mcp/dist/index.js"],
      "env": {
        "LLAMA_CLOUD_API_KEY": "your-api-key-here",
        "LLAMA_CLOUD_ORGANIZATION_ID": "your-organization-id",
        "LLAMA_CLOUD_PIPELINE_ID": "your-pipeline-id"
      }
    }
  }
}

# 4. Restart Cursor IDE

🔧 Prerequisites

• Node.js 18.0+ and npm
• LlamaCloud API Key (get it here)
• LlamaCloud Organization ID
• LlamaCloud Pipeline ID (or a full Pipeline URL)
• Cursor IDE with MCP support

📋 Available Tools

🔍 query_rag

Ask questions about your documents and get comprehensive answers with sources.

Input:

• question (string, 1-1000 chars): Your question about the documents

Output:

• 📝 Detailed answer based on retrieved content
• 📚 List of source documents with relevance scores
• 👀 Preview text from each source

Example:

Question: "What is database normalization?"
Answer: Based on the found documents, database normalization is...
Sources: 
1. Database Design Principles (relevance: 0.95)
2. SQL Fundamentals (relevance: 0.87)

📄 search_documents

Search for relevant documents without generating an answer.

Input:

• query (string, 1-500 chars): Search query
• top_k (number, 1-10, default 5): Number of results

Output:

• 📄 List of matching documents
• 🔍 Content previews and metadata
• 📊 Relevance scores

ℹ️ get_index_info

Get detailed information about your LlamaCloud index.

Input: None

Output:

• 📋 Index name, project, organization details
• ✅ Current status and configuration
• 🔗 Pipeline URL and last update time

🧪 Testing Your Setup

# Test with npm scripts
npm run test

# Manual testing
npm run test:init  # Test initialization
npm run test:tools # Test tool listing

# Test with your API key
LLAMA_CLOUD_API_KEY="your-key" LLAMA_CLOUD_ORGANIZATION_ID="your-org-id" LLAMA_CLOUD_PIPELINE_ID="your-pipeline-id" npm run test

📁 Project Structure

llamacloud-rag-mcp/
├── 📂 src/
│   └── 📄 index.ts           # Main MCP server implementation
├── 📂 dist/                  # Compiled JavaScript (auto-generated)  
├── 📄 package.json           # Node.js configuration
├── 📄 tsconfig.json          # TypeScript configuration
├── 📄 install.sh            # Automated installer
├── 📄 cursor-mcp-config.example.json  # Configuration example
├── 📄 config.example         # LlamaCloud config template
├── 📄 LICENSE               # MIT license
└── 📄 README.md             # This file

🔐 Security & Best Practices

• ✅ API Key Protection: Never commit keys to version control
• ✅ Environment Variables: Secure configuration management
• ✅ Type Safety: Full TypeScript implementation
• ✅ Error Handling: Comprehensive error catching and reporting
• ✅ Input Validation: Secure parameter validation
• ✅ No Data Logging: Your queries stay private

🎨 Customization

Using Your Own LlamaCloud Index

1. Create your index in LlamaCloud
2. Set the required environment variables in your Cursor MCP config:

LLAMA_CLOUD_API_KEY=...
LLAMA_CLOUD_ORGANIZATION_ID=...
LLAMA_CLOUD_PIPELINE_ID=...
# or set LLAMA_CLOUD_PIPELINE_URL=... instead of PIPELINE_ID

3. Rebuild: npm run build

Custom Tools

Extend the server by adding new tools in src/index.ts. Follow the existing patterns for type safety and error handling.

🐛 Troubleshooting

Tools not showing in Cursor?

1. ✅ Check env vars: Ensure LLAMA_CLOUD_API_KEY, LLAMA_CLOUD_ORGANIZATION_ID, and LLAMA_CLOUD_PIPELINE_ID (or LLAMA_CLOUD_PIPELINE_URL) are set correctly
2. 🔄 Restart Cursor: Fully quit and restart Cursor IDE
3. 📍 Check paths: Ensure absolute paths in MCP configuration
4. 🔍 Check logs: Look at Cursor developer console for errors
5. 🧪 Test manually: Run npm run test to verify server works

Common Issues

"Module not found": Run npm run build first "Missing required environment variables": Set LLAMA_CLOUD_API_KEY, LLAMA_CLOUD_ORGANIZATION_ID, and LLAMA_CLOUD_PIPELINE_ID (or LLAMA_CLOUD_PIPELINE_URL)
"Connection failed": Check your LlamaCloud API key and internet connection "Tools not listed": Verify Cursor MCP configuration syntax

Getting Help

• 📖 Check the MCP Documentation
• 💬 Open an issue
• 🔍 Review Cursor logs in developer console

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and open an issue or pull request.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a pull request

📄 License

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

🙏 Acknowledgments

• Model Context Protocol team
• LlamaIndex for the amazing RAG platform
• Cursor IDE for MCP integration
• Cursor MCP Integration Guide 2025 for best practices

Made with ❤️ for the developer community

Star ⭐ this repository if it helped you!