Quick Start Guide

There are two ways to use the Moorcheh MCP server:

Option 1: NPX (Recommended - No Installation Required)

The easiest way to get started:

# Set your API key and run directly
MOORCHEH_API_KEY=your_api_key_here npx -y @moorchehai/mcp

Option 2: Manual Installation

If you prefer to clone and run locally:

1. Clone the repository

   git clone https://github.com/moorcheh-ai/moorcheh-mcp.git
   cd moorcheh-mcp

2. Install dependencies

   npm install

Step 2: Configure Your API Key

1. Get your Moorcheh API key

   • Visit Moorcheh Dashboard
   • Sign in to your account
   • Go to your account settings
   • Generate or copy your API key

2. Set up your environment

   # Copy the example environment file
   cp env.example .env

3. Edit the .env file

   # Open .env in your preferred editor
   # Replace 'your_moorcheh_api_key_here' with your actual API key
   MOORCHEH_API_KEY=your_actual_api_key_here

Step 3: Start the Server

npm start

That's it! Your Moorcheh MCP server is now running and ready to use.

Setting Up with Claude Desktop

To use the Moorcheh MCP server with Claude Desktop:

https://github.com/user-attachments/assets/fccbba8e-7393-4b74-8a73-769b55b3f3a3

Step 1: Install Claude Desktop

1. Download Claude Desktop from https://claude.ai/download
2. Install and launch Claude Desktop

Step 2: Configure MCP Server

Option A: Using NPX (Recommended)

1. In Claude Desktop, go to Settings → Developer
2. Click Edit Config
3. Configure the server with these settings:

   {
      "mcpServers": { 
            "moorcheh": {
               "command": "npx",
               "args": ["-y", "@moorchehai/mcp"],
               "env": {
                  "MOORCHEH_API_KEY": "your_actual_api_key_here"
               }
            }
      }
   }

Option B: Local Installation

1. In Claude Desktop, go to Settings → Developer

2. Click Edit Config

3. Configure the server with these settings:

   {
      "mcpServers":{ 
            "moorcheh": {
               "command": "node",
               "args": [
               "path\\to\\moorcheh-mcp\\src\\server\\index.js"
               ],
               "env": {
               "NODE_ENV": "development"
               }
            }
      }
   }

4. Important:

   • For Option A: Replace your_actual_api_key_here with your actual Moorcheh API key
   • For Option B: Replace path\\to\\moorcheh-mcp\\src\\server\\index.js with the actual path to your index.js file and create .env in moorcheh-mcp with your API key

5. Save the configuration file and restart Claude Desktop completely

Step 3: Test the Connection

1. Start a new conversation in Claude Desktop
2. Ask Claude to list the available tools: "Can you list down my namespaces?"
3. You should see tools like list-namespaces, search, answer, etc.

Setting Up with Cursor

To use the Moorcheh MCP server with Cursor IDE:

Step 1: Install Cursor

1. Download Cursor from https://cursor.com
2. Install and launch Cursor

Step 2: Configure MCP Server

Option A: Using NPX (Recommended)

1. In Cursor, go to Settings → Tools & integration
2. Click Add MCP Server
3. Configure the server with these settings:

{
   "mcpServers": { 
         "moorcheh": {
            "command": "npx",
            "args": ["-y", "@moorchehai/mcp"],
            "env": {
               "MOORCHEH_API_KEY": "your_actual_api_key_here"
            }
         }
   }
}

Option B: Local Installation

1. In Cursor, go to Settings → Tools & integration
2. Click Add MCP Server
3. Configure the server with these settings:

{
   "mcpServers":{ 
         "moorcheh": {
            "command": "node",
            "args": [
            "path\\to\\moorcheh-mcp\\src\\server\\index.js"
            ],
            "env": {
            "NODE_ENV": "development"
            }
         }
   }
}

Step 3: Set Your API Key

• For Option A: Replace your_actual_api_key_here with your actual Moorcheh API key in the configuration
• For Option B: Create .env in moorcheh-mcp directory and add your API key with MOORCHEH_API_KEY=your_key_here

Step 4: Test the Connection

1. Open a new chat in Cursor (Cmd/Ctrl + L)
2. Ask the AI to list available Moorcheh tools: "What Moorcheh tools can I use?"
3. You should see tools like list-namespaces, search, answer, etc.

What This Server Does

The Moorcheh MCP server provides tools for:

• Namespace Management: Create, list, and delete namespaces for organizing your data
• Document Operations: Upload and manage text documents and vector embeddings
• Advanced Search: Perform semantic search across your data
• AI-Powered Answers: Get intelligent responses based on your stored data

Available Tools

Namespace Tools

• list-namespaces: View all your available namespaces
• create-namespace: Create a new namespace for storing data
• delete-namespace: Remove a namespace and all its contents

Data Tools

• upload-text: Upload text documents to a namespace
• upload-vectors: Upload vector embeddings to a namespace
• upload-file: Upload files to a text namespace via pre-signed URL (supported types: .pdf, .docx, .xlsx, .json, .txt, .csv, .md)
• list-files: List raw file objects in S3 storage for a namespace (GET /list-files; see List Files)
• delete-file: Delete one or more raw files from S3 storage (DELETE /delete-file with file_name and/or file_names; see Delete File)
• fetch-text-data: List text and summary chunks from a text namespace (GET /documents/fetch-text-data, up to 100 items per response; see Fetch Text Data)
• get-data: Retrieve text documents by ID from text namespaces
• delete-data: Remove specific data items from a namespace

Search & AI Tools

• search: Search across namespaces with vector similarity
• answer: Get AI-generated answers based on top of your search

Supported AI models

These IDs match the current Moorcheh Available Models list (REST answer / Python answer.generate).

| Model ID | Name | Provider | Description | |----------|------|----------|-------------| | anthropic.claude-sonnet-4-6 | Claude Sonnet 4.6 | Anthropic | Fast flagship: coding, tools, long docs and RAG (~1M context) | | anthropic.claude-opus-4-6-v1 | Claude Opus 4.6 | Anthropic | Deepest reasoning and hardest tasks; pick when quality matters most (~1M context) | | meta.llama4-maverick-17b-instruct-v1:0 | Llama 4 Maverick 17B | Meta | Long context, summarization, function calling, fine-tuning friendly | | amazon.nova-pro-v1:0 | Amazon Nova Pro | Amazon | Chat, math, and structured answers for AWS-style workloads | | deepseek.r1-v1:0 | DeepSeek R1 | DeepSeek | Step-by-step reasoning; math, logic, and technical explanations | | deepseek.v3.2 | DeepSeek V3.2 | DeepSeek | Efficient general Q&A, multilingual, everyday RAG (~164K context) | | openai.gpt-oss-120b-1:0 | OpenAI GPT OSS 120B | OpenAI | Large generalist: research-style answers and long-form writing | | qwen.qwen3-32b-v1:0 | Qwen 3 32B | Qwen | Code and bilingual (EN/ZH) tasks in a smaller footprint | | qwen.qwen3-next-80b-a3b | Qwen3 Next 80B A3B | Qwen | MoE model for long chats, docs, and code at scale (~256K context) |

Prerequisites

• Node.js: Version 18.0.0 or higher
• Moorcheh Account: Active account with API access
• Git: For cloning the repository

Development

Development Mode

For development with auto-reload:

npm run dev

Available Scripts

| Script | Description | |--------|-------------| | npm start | Start the MCP server | | npm run dev | Start in development mode with auto-reload | | npm test | Run tests (when available) |

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | MOORCHEH_API_KEY | Your Moorcheh API key | Yes | None |

Troubleshooting

Common Issues

1. "Missing required API_KEY environment variable"

   • Make sure you've created a .env file
   • Verify your API key is correctly set in the .env file
   • Check that the API key is valid in your Moorcheh dashboard

2. "Forbidden: Check your API key"

   • Your API key may be invalid or expired
   • Generate a new API key from the Moorcheh dashboard
   • Update your .env file with the new key

3. "Network Error"

   • Check your internet connection
   • Verify the API endpoints are accessible
   • Try again in a few minutes

Getting Help

• GitHub Issues: https://github.com/moorcheh-ai/moorcheh-mcp/issues
• Moorcheh Documentation: https://console.moorcheh.ai/docs/mcp
• Moorcheh Dashboard: https://console.moorcheh.ai

License

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

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Changelog

For a detailed list of changes, see CHANGELOG.md.