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

If you want to connect from Claude Web, Genie Code, or any other MCP client, check out the Remote MCP Server and the Client Guides.

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

Automated (Recommended)
Manual Install

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!

Manual installation using pipx:pipx installs the package in an isolated environment and works reliably with Claude Desktop on all platforms.macOS:

brew install pipx
pipx ensurepath
pipx install prometheux-mcp

Windows:

pip install pipx
pipx ensurepath
pipx install prometheux-mcp

Linux:

pip install pipx
pipx ensurepath
pipx install prometheux-mcp

After installation, you’ll need to manually configure Claude Desktop (see Configuration section below).

Configuration

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

Configuration
With Debug Mode

{
  "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"
      }
    }
  }
}

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.

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

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

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

Add --debug flag to see detailed logs in Claude Desktop’s console:

{
  "mcpServers": {
    "prometheux": {
      "command": "/Users/YOUR_USERNAME/.local/bin/prometheux-mcp",
      "args": ["--url", "https://api.prometheux.ai", "--debug"],
      "env": {
        "PROMETHEUX_TOKEN": "your_token_here",
        "PROMETHEUX_USERNAME": "your_username",
        "PROMETHEUX_ORGANIZATION": "your_organization"
      }
    }
  }
}

Replace the command path with your actual path (see previous tab for how to find it).

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.

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:

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:

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

Windows:

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

Linux:

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

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:

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

”Authentication failed” error

Your credentials are incorrect or expired. Solution:

Double-check your token, username, and organization in the config
Verify the credentials with your Prometheux admin
Ensure there are no extra spaces or quotes in the JSON config
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:

Be more explicit: “Use the prometheux tools to list concepts in project X”
Check Claude Desktop’s console for MCP errors (View > Developer > Toggle Developer Tools)
Enable debug mode in your config (--debug flag) and check logs
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

MCP Protocol Specification: modelcontextprotocol.io
Local MCP Server (GitHub): prometheuxresearch/px-mcp-server
Local MCP Server (PyPI): prometheux-mcp
Remote MCP Server: See Remote MCP Server for Claude Web integration
Python SDK: See Python SDK Reference for alternative integration methods
REST API: See REST API Reference for direct HTTP access

Concepts API - Learn about the concept API
Python SDK - Alternative programmatic access
Chat API - Interactive AI chat interface

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Local MCP Server

Local MCP Server for Claude Desktop

Why Use Local MCP?

Quick Start

Prerequisites

Installation

Configuration

1. Get Your Credentials

2. Configure Claude Desktop

3. Restart Claude Desktop

Usage

Troubleshooting

”command not found” or “Server disconnected” error

”Connection refused” error

”Authentication failed” error

Claude doesn’t use the tools

Advanced Usage

Using MCP Programmatically

Local Development

Learn More

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

​Local MCP Server for Claude Desktop

​Why Use Local MCP?

​Quick Start

​Prerequisites

​Installation

​Configuration

​1. Get Your Credentials

​2. Configure Claude Desktop

​3. Restart Claude Desktop

​Usage

​Troubleshooting

​”command not found” or “Server disconnected” error

​”Connection refused” error

​”Authentication failed” error

​Claude doesn’t use the tools

​Advanced Usage

​Using MCP Programmatically

​Local Development

​Learn More

​Related Resources

Local MCP Server for Claude Desktop

Why Use Local MCP?

Quick Start

Prerequisites

Installation

Configuration

1. Get Your Credentials

2. Configure Claude Desktop

3. Restart Claude Desktop

Usage

Troubleshooting

”command not found” or “Server disconnected” error

”Connection refused” error

”Authentication failed” error

Claude doesn’t use the tools

Advanced Usage

Using MCP Programmatically

Local Development

Learn More

Related Resources