Skip to main content

Local MCP Server for Claude Desktop

Connect Claude Desktop to Prometheux using the Model Context Protocol (MCP) — an open standard that enables AI assistants to interact with external tools and data sources.

The local MCP server (prometheux-mcp) runs on your machine alongside Claude Desktop, providing a simple and secure way to integrate AI agents with your Prometheux ontologies.

Why Use Local MCP?​

Best for: Claude Desktop users, development environments, on-premise deployments

Pros:

  • Simple pip install
  • Runs locally (no external dependencies)
  • Full control over credentials
  • Works with any Prometheux instance (cloud or on-premise)

Cons:

  • Requires Claude Desktop app (not available for Claude Web)
  • Needs to be installed on each machine

Use this when:

  • You're using Claude Desktop
  • You want a simple, local installation
  • You're developing or testing locally
Looking for Claude Web Integration?

If you want to use Prometheux with Claude Web (browser-based), check out the Remote MCP Server documentation instead.

Quick Start​

Prerequisites​

  • Prometheux account with access to a deployed instance
  • Claude Desktop installed on your machine (download here)
  • Your credentials: token, username, and organization from your Prometheux admin

Installation​

Easiest method - download and run our installation script:

macOS/Linux:

curl -sSL https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.sh -o install.sh
chmod +x install.sh
./install.sh

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.ps1" -OutFile "install.ps1"
.\install.ps1

The script will:

  • ✅ Install pipx (if not already installed)
  • ✅ Install prometheux-mcp package from PyPI
  • ✅ Prompt for your credentials (URL, token, username, organization)
  • ✅ Automatically configure Claude Desktop
  • ✅ Create backups of existing configuration

Then just restart Claude Desktop and you're ready!

Configuration​

Automated Installation

If you used the automated installation script, configuration was done automatically. Skip to the Usage section below.

For manual installations only:

1. Get Your Credentials​

You'll need:

  • Server URL (e.g., https://api.prometheux.ai or your on-premise URL)
  • Authentication token
  • Username
  • Organization

Contact your Prometheux admin or check your account settings for these credentials.

2. Configure Claude Desktop​

Edit the Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "prometheux": {
      "command": "/Users/YOUR_USERNAME/.local/bin/prometheux-mcp",
      "args": ["--url", "https://api.prometheux.ai"],
      "env": {
        "PROMETHEUX_TOKEN": "your_token_here",
        "PROMETHEUX_USERNAME": "your_username",
        "PROMETHEUX_ORGANIZATION": "your_organization"
      }
    }
  }
}
Finding Your Path

Run this in your terminal to find the full path:

  • macOS/Linux: which prometheux-mcp
  • Windows: where prometheux-mcp (in PowerShell or Command Prompt)

Common paths after pipx install:

  • macOS: /Users/YOUR_USERNAME/.local/bin/prometheux-mcp
  • Windows: C:\\Users\\YOUR_USERNAME\\.local\\bin\\prometheux-mcp.exe
  • Linux: /home/YOUR_USERNAME/.local/bin/prometheux-mcp

Use double backslashes (\\) for Windows paths in JSON.

URL Routing

The server automatically constructs the full API path using your username and organization: {url}/jarvispy/{organization}/{username}/mcp/messages

Custom or On-Premise URLs

For on-premise deployments or custom URLs, replace https://api.prometheux.ai with your own server URL:

"args": ["--url", "https://your-custom-domain.com"]

3. Restart Claude Desktop​

Completely quit Claude Desktop (Cmd+Q on macOS, or close from system tray) and reopen it. The MCP server will start automatically when Claude launches.

Usage​

Once configured, just chat naturally with Claude. The AI will automatically use the Prometheux MCP tools when relevant.

Example Conversations & Available Tools

See the MCP overview page for example conversations and a complete list of available tools.

Troubleshooting​

"command not found" or "Server disconnected" error​

Claude Desktop can't find the prometheux-mcp command.

Solution:

Quick Fix

If you used manual installation, try the automated installation script instead - it handles all path configuration automatically:

# macOS/Linux
curl -sSL https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
# Windows
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/prometheuxresearch/px-mcp-server/main/install.ps1" -OutFile "install.ps1"; .\install.ps1

Manual fix:

macOS:

  1. Find the full path: which prometheux-mcp
  2. Use that full path in your config (usually /Users/YOUR_USERNAME/.local/bin/prometheux-mcp)
  3. Restart Claude Desktop completely (Cmd+Q, then reopen)

Windows:

  1. Find the full path: where prometheux-mcp (in PowerShell or Command Prompt)
  2. Use that full path in your config with double backslashes (e.g., C:\\Users\\YOUR_USERNAME\\.local\\bin\\prometheux-mcp.exe)
  3. Restart Claude Desktop

Linux:

  1. Find the full path: which prometheux-mcp
  2. Use that full path in your config (usually /home/YOUR_USERNAME/.local/bin/prometheux-mcp)
  3. Restart Claude Desktop
tip

GUI applications like Claude Desktop may not inherit your terminal's PATH. Using the full path is more reliable than the short command.

"Connection refused" error​

The MCP server can't reach your Prometheux instance.

Solution:

  1. Verify your server URL is correct and accessible
  2. Test the connection: curl https://your-server-url/mcp/info
  3. Check if you're behind a VPN or firewall that might block access
  4. For on-premise installations, ensure the server is running

"Authentication failed" error​

Your credentials are incorrect or expired.

Solution:

  1. Double-check your token, username, and organization in the config
  2. Verify the credentials with your Prometheux admin
  3. Ensure there are no extra spaces or quotes in the JSON config
  4. Check if your token has expired and needs renewal

Claude doesn't use the tools​

Claude might not realize the tools are relevant to your query.

Solution:

  1. Be more explicit: "Use the prometheux tools to list concepts in project X"
  2. Check Claude Desktop's console for MCP errors (View → Developer → Toggle Developer Tools)
  3. Enable debug mode in your config (--debug flag) and check logs
  4. Verify the server is connected: look for the hammer icon in Claude Desktop

Advanced Usage​

Using MCP Programmatically​

You can also use the Prometheux MCP package as a Python library:

import asyncio
from prometheux_mcp.config import Settings
from prometheux_mcp.client import PrometheuxClient

async def main():
    # Configure connection
    settings = Settings(
        url="https://api.prometheux.ai",
        token="your_token",
        username="your_username",
        organization="your_org"
    )
    
    # Create client
    async with PrometheuxClient(settings) as client:
        # List concepts
        concepts = await client.list_concepts("project-123")
        print(f"Found {concepts['count']} concepts")
        
        # Run a concept
        result = await client.run_concept(
            project_id="project-123",
            concept_name="my_concept",
            force_rerun=True
        )
        print(f"Derived {result['total_records']} records")

asyncio.run(main())

Local Development​

To test MCP locally with your development instance:

{
  "mcpServers": {
    "prometheux-local": {
      "command": "prometheux-mcp",
      "args": ["--url", "http://localhost:8000", "--debug"],
      "env": {
        "PROMETHEUX_TOKEN": "dev_token",
        "PROMETHEUX_USERNAME": "dev_user",
        "PROMETHEUX_ORGANIZATION": "dev_org"
      }
    }
  }
}

Learn More​