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

The server supports two transport modes:

• stdio (default): Standard input/output for use with Claude Desktop and other MCP clients
• Streamable HTTPS: HTTP/HTTPS endpoint for web-based integrations

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 by default and can be used with MCP clients like Claude.

For HTTP/HTTPS mode (streamable), see the streamable_https.md documentation.

Proxy Configuration

The server automatically respects system proxy settings via environment variables. This works with npx, global installations, and local development.

Setting Proxy Environment Variables

# For HTTP connections
export HTTP_PROXY="http://proxy.example.com:8080"
export http_proxy="http://proxy.example.com:8080"

# For HTTPS connections
export HTTPS_PROXY="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"

# Optional: Bypass proxy for specific domains (comma-separated)
export NO_PROXY="localhost,127.0.0.1,10.0.0.0/8"
export no_proxy="localhost,127.0.0.1,10.0.0.0/8"

Using with npx

# Set proxy variables, then run npx
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"

npx @morphik/mcp --uri=http://your-morphik-server:port

Using with Claude Desktop

When using Claude Desktop, you can set environment variables in the configuration:

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

{
  "mcpServers": {
    "morphik": {
      "command": "npx",
      "args": ["-y", "@morphik/mcp", "--uri=http://your-server:port"],
      "env": {
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

Note: The server checks both uppercase and lowercase versions of proxy environment variables for compatibility.

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

See MCP_TOOLS.md for detailed parameter docs and response formats.

The server currently provides the following tools, with additional capabilities on the way:

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-file-from-base64: Upload a file by providing its filename plus base64-encoded bytes (works in HTTP transports where disk access isn't possible)

  • Parameters: filename, base64Content, 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 & Navigation

• retrieve-chunks: Retrieve the most relevant "pages" (text or image chunks) for a query, identical to the find_relevant_pages tool in @morphik-app

  • Parameters: query, filters (optional), k (optional), minScore (optional), folderName (optional), endUserId (optional), useColpali/useReranking (optional), padding (optional for adjacent context)

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

  • Parameters: query, filters (optional), k (optional), minScore (optional), folderName (optional), endUserId (optional)

• search-documents: Search for documents by filename or title using full-text search

  • Parameters: query, limit (optional, 1-100), folderName (optional), endUserId (optional)

• get-pages-in-range: Fetch an inclusive range of pages (max 10) from a document, matching get_all_pages_within_range_from_document in @morphik-app

  • Parameters: documentId, startPage, endPage, folderName (optional), endUserId (optional)

3. Document Management & Metadata

• 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

• check-ingestion-status: Check the processing status for an ingested document

  • Parameters: documentId, apiKey

• morphik-filters: View, set, or clear typed metadata filters that automatically apply to retrieval/list operations (supports eq, regex, number_range, date_range)

  • Parameters: action, expression/rules payload, logic (optional)

• list-documents: Updated tool using /documents/list_docs with include_total_count, return_documents, fields, and folder/end-user scoping

  • Parameters: skip, limit, filters/metadataFilters, get_count, folderName(s), endUserId, sortBy/sortDirection, fields

4. 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