MCP Integration - Figranium

The Figranium MCP Server is a Model Context Protocol (MCP) server for Figranium built using the official @modelcontextprotocol/sdk. This integration allows LLM clients such as Claude Desktop, Cursor, and Manus AI to seamlessly discover, execute, inspect, schedule, and programmatically construct Figranium browser automation tasks via standard STDIO transport. With this server, your AI assistant or agent can autonomously navigate the web, scrape structured data, handle multi-step workflows, and manage automated schedules directly using Figranium.

The Model Context Protocol (MCP) is an open standard that lets AI applications securely connect to external data sources and tools. The Figranium MCP server exposes tasks, executions, and schedules as discoverable resources and callable tools.

Quick Start (NPM / NPX)

The recommended way to run the Figranium MCP server is via npx from npm. This lets you launch the official package directly without cloning the repository.

npx -y figranium-mcp

If you prefer containerized deployment, you can also use the official OCI image from GitHub Container Registry:

docker pull ghcr.io/figranium/figranium-mcp:latest

Client Integration

Claude.ai (recommended)

Figranium exposes a hosted remote MCP endpoint that can be connected directly from Claude.ai. You do not need to run the MCP server locally or install the desktop app for this flow.

Open Claude connectors

In Claude.ai, open Customize > Connectors, then choose Add custom connector.

Add Figranium

Enter:

Name: Figranium
MCP URL: https://mcp.figranium.dev/mcp

Leave custom OAuth client ID/secret fields empty. Figranium supports OAuth client registration automatically.

Connect with OAuth

Choose Connect. Claude redirects you to Figranium’s hosted authorization page.

Enter your Figranium connection

Provide the full base URL of your Figranium instance, including the scheme, for example:

https://figranium.example.com/

Then enter the API key generated by that instance. See Get Your Figranium API Key to find or generate it.

Approve and use Figranium

After authorization completes, Claude discovers the available Figranium tools automatically. You can then ask Claude to list tasks, inspect executions, run tasks, and manage supported Figranium operations.

The hosted OAuth service at mcp.figranium.dev stores your Figranium instance URL and encrypted API key so Claude can reconnect without asking for your credentials on every request.

Your Figranium instance must be reachable from the public internet for Claude’s cloud-hosted connector to access it. Use HTTPS for production instances whenever possible.

Claude Desktop
Cursor IDE
Manus AI / Registry Clients

To connect Claude Desktop to your Figranium MCP server, update your client configuration file:

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

Add the following configuration block under mcpServers:

{
  "mcpServers": {
    "figranium": {
      "command": "npx",
      "args": ["-y", "figranium-mcp"],
      "env": {
        "FIGRANIUM_BASE_URL": "http://localhost:11345",
        "FIGRANIUM_API_KEY": "[your_figranium_api_key_here]"
      }
    }
  }
}

Note for Local Hosts: If you run the server from within Docker, use http://host.docker.internal:11345 so the container can route traffic back to your host system. For local npx execution, use http://localhost:11345.

You can easily integrate Figranium into your Cursor environment as an MCP server:

Open MCP settings

Navigate to Settings > Features > MCP.

Add a new server

Click Add New MCP Server.

Configure parameters

Configure the following parameters:

Name: figranium
Type: command
Command: npx -y figranium-mcp
Environment Variables:
- FIGRANIUM_BASE_URL=http://localhost:11345
- FIGRANIUM_API_KEY=[your_figranium_api_key_here]

Note for Local Hosts: Use http://localhost:11345 when running the MCP server locally via npx. If you choose to run the MCP server inside Docker instead, swap the base URL to http://host.docker.internal:11345.

For platforms and clients that support automatic registry resolution, you can configure and register the MCP server using its official registry namespace:

io.github.figranium/figranium-mcp

This namespace points to the official GHCR OCI identifier which compatible clients resolve and download automatically.

Environment Variables

The Figranium MCP server expects the following environment variables:

Variable	Description	Default
`FIGRANIUM_BASE_URL`	Base URL of your running Figranium API.	`http://localhost:11345`
`FIGRANIUM_API_KEY`	Your Figranium API key from Settings > API Keys. See Get Your Figranium API Key.	(Required)

Server-Wide System Instructions

The server initializes and communicates a predefined set of instructions directly to the connected LLM client. These instructions govern how the agent interacts with Figranium throughout a task’s lifecycle:

1. Task Creation and Execution Environments

Task Modes: Fast, non-interactive tasks should use the scrape mode. Detailed, interactive, multi-step tasks requiring complex mouse and keyboard simulation should use the agent mode.
Headful Execution: For debugging or executing tasks that require a visible environment, headful execution is supported to let you visually inspect interactions in real-time.
Stealth Configurations: Anti-bot stealth mechanisms can be toggled inside the stealth configuration block. These simulate organic mouse curves, natural delays, randomized click offsets, and other human-like interactions.

2. Step Sequence Construction (Actions)

Automation workflows are organized sequentially in the actions array.
Supported actions include navigation (navigate, reload), waits (wait, wait_selector, wait_downloads), interactions (click with single, double, or right click modes; check, uncheck, drag_and_drop, select, type, hover, press, scroll), custom scripts (javascript), control flow (if, else, end, while, repeat, foreach), CAPTCHA actions (solve_captcha, wait_captcha), and file actions (upload, finalize_uploads).
Tasks can also set cabinetId to choose the Cabinet that receives intercepted downloads. An upload action can optionally set downloadCabinetId and markAsUploaded; otherwise it uses the task/default Cabinet and can be finalized later with finalize_uploads.
Agent and headful tasks can opt in to translation: { enabled: true, targetLanguage } so rendered page text is translated before actions and re-applied after navigation. Translation is unavailable in scrape mode.
Add wait_selector only when readiness actually requires it. Do not add waits automatically before every interaction.
Prefer native Figranium actions over JavaScript, and avoid redundant navigate, wait, loop, or start / “On Execution” blocks when task-level behavior already covers them.

3. Target Selector Strategy

Prefer highly robust and resilient selector targets: IDs (e.g., #[your-css-selector]), semantic class names, ARIA roles, or reliable text matches.
Avoid fragile, heavily nested structural paths (e.g. div > div > span > button) that are prone to breakage.
When targeting elements inside the Shadow DOM, set the includeShadowDom property to true.

4. Variables and Execution Context

Task-level variables are inputs/configuration that callers may override before execution. Do not use task variables as final output fields.
Use set for runtime or mid-task state needed by later blocks; it may create or update a runtime variable.
Values that depend on execution time, such as “today”, “last 7 days”, or “past 90 days”, must remain dynamic rather than being hard-coded during task creation.
Initiate runs via the task_execute tool, and pass variable overrides to change defaults dynamically during execution.

5. Source, Extraction, and Result Validation

Prefer the simplest native workflow that reliably satisfies the request. Do not add actions or configuration that serve no concrete purpose.
When no source is specified, choose one that directly represents the requested data. Prefer structured first-party/public APIs when they reliably provide the needed information.
Final structured output, including table parsing/extraction, must be implemented in the task-level extractionScript field. Do not treat task variables or ordinary JavaScript action blocks as final extraction output.
When extracting lists, return consistently structured records and remove obvious duplicates when appropriate.
Unless the user explicitly asks not to test, execute a created or updated task and inspect the actual returned result. A success execution status alone is not enough.
Verify that the output meaningfully satisfies the request. If it is empty, malformed, irrelevant, duplicated, unexpectedly null, or otherwise incorrect, fix the task and execute it again.
Preserve reasonable implementation ambiguity, avoid inventing unnecessary requirements, and make sensible implementation decisions when needed to complete the task.

Available Resources

`figranium://schemas/task-v1.json`

MIME Type: application/json
Description: Exposes the complete JSON Schema definition for a Figranium task. Connected agents read this resource to understand valid action steps, nested attributes, and execution parameters.

Available Tools

The MCP server exposes rich tools mapped to Figranium’s REST API.

Task Operations

create_task
- Creates a completely configured Figranium task.
- Parameters: Name, starting URL, execution mode (scrape or agent), stealth settings, actions array, variables, optional cabinetId, and scheduling details.
task_list
- Fetches all task IDs, names, and descriptions registered on the server.
task_execute
- Triggers the execution of a task by ID. Supports runtime variable overrides.

Cabinet Operations

`list_cabinets`

Lists Cabinets available on the connected Figranium instance so an agent can choose a destination or source by ID.

`create_cabinet`

Creates a Cabinet that can then be referenced by cabinetId in a task or Upload action.

These tools pair with the upload and finalize_uploads action types.

Execution Operations

execution_list
- Retrieves a summary of previous task execution logs, run durations, and final statuses.

Schedule Operations

schedule_list
- Lists all task IDs with active, configured schedules.
schedule_get_all_status
- Returns the overall status of the scheduler engine.
schedule_get_status
- Fetches the active schedule rules and next calculated run time for a given taskId.
schedule_set
- Registers or updates a task schedule using either a structured Frequency format or standard Cron expressions.
schedule_delete
- Disables and removes scheduling rules from a task.
schedule_describe
- Validates and previews schedule execution intervals and next run times without committing changes.

Rich Input Diagnostics & Self-Correction

When an LLM client calls create_task with malformed arguments, the Figranium MCP server returns structured, highly descriptive Zod validation errors, setting isError: true. This structured output allows advanced LLMs to pinpoint schema mismatches and perform immediate, automatic self-correction. For example, if an agent provides a typo in an action step’s type field, the server returns:

Schema Validation Failed!

Detailed breakdown of validation errors:
 - At Step Index 2 (action step #3), parameter "type" failed validation: Invalid enum value. Expected 'click' | 'type' | 'wait' ..., received 'clikc'

Using this feedback, the LLM corrects 'clikc' to 'click' and retries the command autonomously.

Local Development & Source Build

To build the Figranium MCP server locally from source:

Prerequisites

Node.js: v18+
NPM: v9+

Build Steps

Clone the repository

git clone https://github.com/figranium/figranium-mcp.git
cd figranium-mcp

Install and build

npm install
npm run build

Run the server

npm start

You can also run the TypeScript compiler in watch-mode during active development:

npm run watch

Inspecting & Debugging

To debug the server’s tools, schemas, and resource outputs, use the official MCP Inspector utility:

npx @modelcontextprotocol/inspector node dist/index.js

​Quick Start (NPM / NPX)

​Client Integration

​Claude.ai (recommended)

​Environment Variables

​Server-Wide System Instructions

​1. Task Creation and Execution Environments

​2. Step Sequence Construction (Actions)

​3. Target Selector Strategy

​4. Variables and Execution Context

​5. Source, Extraction, and Result Validation

​Available Resources

​figranium://schemas/task-v1.json

​Available Tools

​Task Operations

​Cabinet Operations

list_cabinets

create_cabinet

​Execution Operations

​Schedule Operations

​Rich Input Diagnostics & Self-Correction

​Local Development & Source Build

​Prerequisites

​Build Steps

​Inspecting & Debugging

Quick Start (NPM / NPX)

Client Integration

Claude.ai (recommended)

Environment Variables

Server-Wide System Instructions

1. Task Creation and Execution Environments

2. Step Sequence Construction (Actions)

3. Target Selector Strategy

4. Variables and Execution Context

5. Source, Extraction, and Result Validation

Available Resources

`figranium://schemas/task-v1.json`

Available Tools

Task Operations

Cabinet Operations

`list_cabinets`

`create_cabinet`

Execution Operations

Schedule Operations

Rich Input Diagnostics & Self-Correction

Local Development & Source Build

Prerequisites

Build Steps

Inspecting & Debugging