rossum-mcp 2.1.0

MCP server for AI-powered Rossum orchestration: document workflows, debug pipelines automatically, and configure intelligent document processing through natural language.

Rossum MCP Server

MCP server for AI-powered Rossum document processing. Fully typed tools with Pydantic models, StrEnum parameters, and unified APIs — built for agents.

[!NOTE] This is not an official Rossum project. It is a community-developed integration built on top of the Rossum API, not a product (yet).

Quick Start

# Set environment variables
export ROSSUM_API_TOKEN="your-api-token"
export ROSSUM_API_BASE_URL="https://api.elis.rossum.ai/v1"

# Run the MCP server
uv pip install rossum-mcp
rossum-mcp

Or run from source:

git clone https://github.com/stancld/rossum-agents.git
cd rossum-agents/rossum-mcp
uv sync
python rossum_mcp/server.py

Claude Desktop Configuration

Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "rossum": {
      "command": "python",
      "args": ["/path/to/rossum-agents/rossum-mcp/rossum_mcp/server.py"],
      "env": {
        "ROSSUM_API_TOKEN": "your-api-token",
        "ROSSUM_API_BASE_URL": "https://api.elis.rossum.ai/v1",
        "ROSSUM_MCP_MODE": "read-write"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
ROSSUM_API_TOKEN	Yes	Your Rossum API authentication token
ROSSUM_API_BASE_URL	Yes	Base URL for the Rossum API
ROSSUM_MCP_MODE	No	read-write (default) or read-only
ROSSUM_MCP_LOG_LEVEL	No	Logging level (default: INFO)

Read-Only Mode

Set ROSSUM_MCP_MODE=read-only to disable all CREATE, UPDATE, and UPLOAD operations. Only GET and LIST operations will be available.

Checking the Current Mode

Use get_mcp_mode to query the current operation mode:

User: What mode are we in?
Assistant: [calls get_mcp_mode] → "read-only"

To change the mode, restart the server with a different ROSSUM_MCP_MODE environment variable.

Available Tools

A compact, fully-typed tool surface — Pydantic models, StrEnum parameters, and consolidated APIs built for agents:

Category	Description
Read Layer	Get any entity by ID or search/list with typed filters
Delete Layer	Unified delete for any supported entity by ID
Document Processing	Upload documents, retrieve content, update/confirm/copy annotations
Queue Management	Create and configure queues (including from templates)
Schema Management	Define, modify, patch, and prune field structures
Engine Management	Configure extraction and splitting engines
Extensions (Hooks)	Webhooks, serverless functions, template-based creation, testing
Rules & Actions	Business rules with TxScript triggers and actions
Workspace Management	Create workspaces
Organization & Users	Feature flags, user creation and updates
Email Templates	Automated email responses
MCP Mode	Get/set read-only or read-write mode at runtime
Tool Discovery	Dynamic tool loading via list_tool_categories

Tool List by Category

Read Layer (unified get + search replacing ~25 individual get_X/list_X tools): get, search

Supported entities for get (by ID): queue, schema, hook, engine, rule, user, workspace, email_template, organization_group, organization_limit, annotation, relation, document_relation, hook_secrets_keys

Supported entities for search (with typed filters): all get entities except organization_limit and hook_secrets_keys, plus search-only entities hook_log, hook_template, user_role, queue_template_name

Delete Layer (unified delete replacing individual delete_X tools): delete

Supported entities: queue, schema, hook, rule, workspace, annotation

Document Processing: upload_document, get_annotation_content, start_annotation, bulk_update_annotation_fields, confirm_annotation, copy_annotations

Queue Management: create_queue_from_template, update_queue

Schema Management: patch_schema, get_schema_tree_structure, prune_schema_fields

Engine Management: create_engine, update_engine, create_engine_field, get_engine_fields

Extensions (Hooks): create_hook, update_hook, create_hook_from_template, test_hook

Rules & Actions: create_rule, patch_rule

Workspace Management: create_workspace

User Management: create_user, update_user

Email Templates: create_email_template

MCP Mode: get_mcp_mode

Tool Discovery: list_tool_categories

For detailed API documentation with parameters and examples, see TOOLS.md.

Example Workflows

Upload and Monitor

# 1. Upload document
upload_document(file_path="/path/to/invoice.pdf", queue_id=12345)

# 2. Get annotation ID
annotations = search(query={"entity": "annotation", "queue_id": 12345, "ordering": ["-created_at"]}, first_n=1)

# 3. Check status
annotation = get(entity="annotation", entity_id=annotations[0]["id"])

Update Fields

# 1. Start annotation (moves to 'reviewing')
start_annotation(annotation_id=12345)

# 2. Get content with field IDs
annotation_content = get_annotation_content(annotation_id=12345)
# Returns {"path": "/tmp/rossum_annotation_12345_content.json"} — use jq/grep on that file

# 3. Update fields using datapoint IDs
bulk_update_annotation_fields(
    annotation_id=12345,
    operations=[{"op": "replace", "id": 67890, "value": {"content": {"value": "INV-001"}}}]
)

# 4. Confirm
confirm_annotation(annotation_id=12345)

License

MIT License - see LICENSE for details.

Resources

• Full Documentation
• Tools Reference
• Rossum API Documentation
• Model Context Protocol
• Main Repository