Morphik MCP

A Model Context Protocol (MCP) server implementation for Morphik multi-modal database.

Overview

This MCP server allows Claude and other MCP-compatible AI assistants to interact with the Morphik database system, enabling:

• Document ingestion (text and files)
• Document retrieval (by relevance to queries)
• Document querying with LLM-powered completions
• Document management (listing, getting, deleting)
• File system navigation and file ingestion from paths

Prerequisites

You need access to either:

• A local Morphik server running on localhost:8000, or
• The Morphik cloud platform

Installation & Usage

Option 1: Run directly with npx (recommended)

# Connect to local Morphik server
npx morphik-mcp

# Connect to Morphik cloud platform (replace with your actual URI)
npx morphik-mcp --uri=https://api.morphik.ai

# Specify allowed directories for file operations (comma-separated)
npx morphik-mcp --allowed-dir=~/Documents,~/Downloads

Option 2: Global installation

npm install -g morphik-mcp

# Connect to local Morphik server
morphik-mcp

# Connect to Morphik cloud platform
morphik-mcp --uri=https://api.morphik.ai

# Specify allowed directories for file operations
morphik-mcp --allowed-dir=~/Documents,~/Downloads

Option 3: Local development

# Clone the repository
git clone https://github.com/morphik-org/morphik-npm-mcp.git
cd morphik-npm-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server (local Morphik)
npm start

# Start the server with file operations enabled
node build/index.js --allowed-dir=~/Documents,~/Downloads

The server runs on standard input/output streams and can be used with MCP clients like Claude.

Usage with Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "morphik-local": {
      "command": "npx",
      "args": ["-y", "morphik-mcp"]
    },
    "morphik-cloud": {
      "command": "npx",
      "args": ["-y", "morphik-mcp", "--uri=https://api.morphik.ai"]
    },
    "morphik-with-files": {
      "command": "npx",
      "args": ["-y", "morphik-mcp", "--allowed-dir=~/Documents,~/Downloads"]
    }
  }
}

MCP Tools

The server provides the following tools:

1. Document Ingestion

• ingest-text: Ingest a text document into Morphik

  • Parameters: content, filename (optional), metadata (optional), apiKey

• ingest-file-from-path: Ingest a file from the server's filesystem into Morphik

  • Parameters: path, metadata (optional), rules (optional), folderName (optional), endUserId (optional), useColpali (optional)

• ingest-files-from-paths: Batch ingest multiple files from the server's filesystem

  • Parameters: paths, metadata (optional), rules (optional), folderName (optional), endUserId (optional), useColpali (optional)

2. Document Retrieval

• retrieve-chunks: Retrieve relevant chunks from Morphik based on a query

  • Parameters: query, filters (optional), k (optional), minScore (optional), apiKey

• retrieve-docs: Retrieve relevant documents from Morphik based on a query

  • Parameters: query, filters (optional), k (optional), minScore (optional), apiKey

3. Document Querying

• query: Generate a completion using relevant chunks as context
  • Parameters: query, filters (optional), k (optional), maxTokens (optional), temperature (optional), apiKey

4. Document Management

• list-documents: List documents in Morphik

  • Parameters: skip (optional), limit (optional), filters (optional), apiKey

• get-document: Get a specific document from Morphik by ID

  • Parameters: documentId, apiKey

• delete-document: Delete a document from Morphik by ID

  • Parameters: documentId, apiKey

5. File System Navigation

• list-allowed-directories: List directories that the server is allowed to access

  • Parameters: none

• list-directory: List files and subdirectories in a specific directory

  • Parameters: path

• search-files: Search for files matching a pattern in a directory and its subdirectories

  • Parameters: path, pattern, excludePatterns (optional)

• get-file-info: Get detailed information about a file or directory

  • Parameters: path

File Operations Security

For security reasons, file operations are restricted to directories explicitly allowed when starting the server using the --allowed-dir parameter. If no directories are specified, only the user's home directory will be accessible.

The server validates all file paths to ensure they're within allowed directories, preventing access to sensitive system files. Symlinks are also checked to ensure they don't point outside allowed directories.

Development

Build the project:

npm run build

Run tests:

npm test

Run manual tests:

npm run test:manual

License

ISC