home / mcp / percepta mcp server

Percepta MCP Server

Provides local, single-user access to browser automation, AI analysis, vision processing, web crawling, automated testing, and DevTools analysis.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "0x-hewm-percepta-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "src.percepta_mcp.server"
      ],
      "env": {
        "PERCEPTA_HOST": "0.0.0.0",
        "PERCEPTA_PORT": "8000",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY",
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY",
        "PERCEPTA_LOG_LEVEL": "INFO"
      }
    }
  }
}

Percepta MCP Server is a local, single-user toolset that combines browser automation, AI analysis, vision processing, web crawling, automated test generation, and DevTools analytics. It runs locally to help you automate tasks, analyze content, and extract structured data without exposing services publicly.

How to use

You run the MCP server locally and connect with an MCP client to perform browser automation, AI analysis, image processing, and data extraction tasks. Start the server, then point your client to the local endpoint to begin issuing tasks and receiving results. Use the client to configure which AI providers to use, which browser to automate, and which data to extract.

How to install

# Prerequisites
# - Python 3.12+
# - uvx (referred to as uv) or pip

# Local install and run
# 1. Clone the project
git clone <repository-url>
cd percepta-mcp

# 2. Install dependencies (recommended using uv)
uv venv
uv sync

# 3. Configure environment variables
cp .env.example .env
# Edit .env to add your API keys

# 4. Install browser driver
uv run playwright install chromium

# 5. Start the MCP server
uv run python -m src.percepta_mcp.server
```

```bash
# Docker deployment (alternative)

# 1. Configure environment variables
cp .env.example .env
# Edit .env with your keys

# 2. Build and start containers
docker-compose up -d

# 3. Check status
docker-compose ps
curl http://localhost:8000/health

Configuration and environment

The server accepts environment variables to control API access, host, port, and log level. Important variables include opensai, anthropic, and Google API keys, plus host/port and log level for runtime customization.

Environment variables

{
  "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
  "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY",
  "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY",
  "PERCEPTA_HOST": "0.0.0.0",
  "PERCEPTA_PORT": 8000,
  "PERCEPTA_LOG_LEVEL": "INFO"
}

MCP client configuration (examples)

{
  "mcpServers": {
    "percepta-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.percepta_mcp.server"]
    }
  }
}

Available tools

Browser automation

Navigate pages, interact with elements, take screenshots, and fill forms in automated browser sessions.

AI analysis

Leverage providers like OpenAI, Anthropic, Google, and Ollama to analyze content, generate insights, and guide automation.

Vision processing

Analyze images with OCR, object detection, and visual understanding to extract data from visuals.

Web crawling

Smart data extraction and structured scraping from websites.

Automated testing

AI-assisted generation and execution of test cases.

DevTools analysis

Performance monitoring and anomaly detection for web pages.