rossum-mcp 1.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. 59 tools for queues, schemas, hooks, engines, and more.

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

[!NOTE] API is stable starting from 1.0.0. Breaking changes will follow SemVer (released as 2.0.0+).

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-mcp/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-mcp/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

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.

Runtime Mode Switching

Two tools allow dynamic mode control:

Tool	Description
get_mcp_mode	Returns current operation mode (read-only or read-write)
set_mcp_mode	Switches between modes at runtime

Use case: Start in read-only mode for safe exploration, then switch to read-write when ready to make changes.

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

User: I'm ready to update the schema now.
Assistant: [calls set_mcp_mode("read-write")] → Mode switched to read-write
           [calls update_schema(...)]

Available Tools

The server provides 59 tools organized into categories:

Category	Tools	Description
Document Processing	7	Upload documents, retrieve/update/confirm/delete annotations
Queue Management	9	Create, configure, delete, and list queues
Schema Management	8	Define, modify, and delete field structures
Engine Management	6	Configure extraction and splitting engines
Extensions & Rules	14	Webhooks, serverless functions, business rules
Workspace Management	4	Organize and delete workspaces
User Management	3	List users and roles
Relations	4	Annotation and document relations
Email Templates	3	Automated email responses
Tool Discovery	1	Dynamic tool loading

Tool List by Category

Document Processing: upload_document, get_annotation, list_annotations, start_annotation, bulk_update_annotation_fields, confirm_annotation, delete_annotation

Queue Management: get_queue, list_queues, get_queue_schema, get_queue_engine, create_queue, create_queue_from_template, get_queue_template_names, update_queue, delete_queue

Schema Management: get_schema, list_schemas, create_schema, update_schema, patch_schema, get_schema_tree_structure, prune_schema_fields, delete_schema

Engine Management: get_engine, list_engines, create_engine, update_engine, create_engine_field, get_engine_fields

Extensions & Rules: get_hook, list_hooks, create_hook, update_hook, list_hook_templates, create_hook_from_template, list_hook_logs, delete_hook, get_rule, list_rules, create_rule, update_rule, patch_rule, delete_rule

Workspace Management: get_workspace, list_workspaces, create_workspace, delete_workspace

User Management: get_user, list_users, list_user_roles

Relations: get_relation, list_relations, get_document_relation, list_document_relations

Email Templates: get_email_template, list_email_templates, create_email_template

Tool Discovery: list_tool_categories

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

Annotation Workflow

Documents progress through these states:

importing → to_review → reviewing → confirmed → exporting → exported

Key points:

• Wait for to_review before processing
• Call start_annotation before updating fields
• Call confirm_annotation to finalize

Example Workflows

Upload and Monitor

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

# 2. Get annotation ID
annotations = list_annotations(queue_id=12345)

# 3. Check status
annotation = get_annotation(annotation_id=annotations[0].id)

Update Fields

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

# 2. Get content with field IDs
annotation = get_annotation(annotation_id=12345, sideloads=['content'])

# 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 file for details.

Resources

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