MCP Integration

Preset Mode

MCP functionality currently has no preset packages available. Manual installation and configuration through plugin mode is required.

Plugin Mode

Installation

npm install @univerjs-pro/mcp @univerjs-pro/mcp-ui @univerjs-pro/sheets-mcp

Usage

import { UniverMCPPlugin } from '@univerjs-pro/mcp'
import { UniverMCPUIPlugin } from '@univerjs-pro/mcp-ui'
import UniverMCPUIEnUS from '@univerjs-pro/mcp-ui/locale/en-US'
import { UniverSheetMCPPlugin } from '@univerjs-pro/sheets-mcp'
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetPlugin } from '@univerjs/sheets' // Basic spreadsheet functionality

import '@univerjs-pro/mcp/facade'
import '@univerjs-pro/mcp-ui/lib/index.css'

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverMCPUIEnUS,
    ),
  },
})

// 1. Basic spreadsheet functionality (required)
univer.registerPlugin(UniverSheetPlugin)

// 2. MCP core communication plugin (required)
univer.registerPlugin(UniverMCPPlugin, {
  ticketServerUrl: 'https://mcp.univer.ai/api/ticket',
  mcpServerUrl: 'wss://mcp.univer.ai/api/ws',
})

// 3. MCP tool registration plugin (required) - automatically exposes 30+ spreadsheet operation tools
univer.registerPlugin(UniverSheetMCPPlugin)

// 4. (Optional) Debug UI plugin
univer.registerPlugin(UniverMCPUIPlugin, {
  showDeveloperTools: true, // Show MCP tool panel for debugging
})

Configuration

Session ID

UniverMCPPlugin uses sessionId: 'default' by default, but:

• Each sessionId only allows one active connection
• In multi-user scenarios, a unique ID must be assigned for each user/workbook

You can specify it in the following way:

// Pass in UniverMCPPlugin configuration (recommended)
univer.registerPlugin(UniverMCPPlugin, {
  sessionId: 'user-123-workbook-abc', // ← Generate dynamically, such as UUID
  // ...other configurations
})

UniverMCPPlugin Configuration Parameters

UniverMCPUIPlugin Configuration Options

UniverMCPUIPlugin provides a visual configuration interface to simplify development and debugging:

univer.registerPlugin(UniverMCPUIPlugin, {
  showDeveloperTools: true, // Show developer tools and configuration interface
})

Key Features:

• Visual API Key Configuration: Supports direct API Key configuration in the interface without hardcoding
• Secure Storage: API Key is securely stored in browser local cache and not distributed to server
• Developer Tools: Provides debugging and monitoring tools for development debugging

Usage Examples

Preparation

Before starting, you need to prepare MCP Server connection:

1. Register API Key: Visit console.univer.ai to apply for API Key
2. Choose Service Mode: Currently provides official cloud service, private deployment service expected in Q4

Start Univer Instance

Before configuring MCP Agent, you must first start a Univer instance with MCP plugins registered. There are two ways:

Method 1: Use Online Playground

1. Visit MCP Playground
2. Remember the displayed session_id (or customize one)

Method 2: Integrate into Existing Project

1. Refer to univer-mcp-start-kit to integrate MCP functionality into your project
2. Ensure the sessionId configuration in your project matches the MCP Agent configuration

Configure MCP Agent (LLM Client)

Configure service address in MCP-supported Agent:

{
  "mcpServers": {
    "univer": {
      "url": "https://mcp.univer.ai/mcp/?univer_session_id=user-123-workbook-abc",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Configuration explanation:

• YOUR_API_KEY: Obtain from https://console.univer.ai
• univer_session_id: Must strictly match the sessionId of Univer instance, this is the key to connection

Verify Connection

After configuration, you can verify the connection in the following ways:

1. Check Tool List: You should be able to see 30+ Univer tools in the MCP client
2. Test Simple Operations: Try asking "write Hello in cell A1"
3. Observe Univer Instance: You should see real-time changes in the instance

Troubleshooting

Tools Not Enabled or List Empty

This is the most common issue. Please check in the following order:

1. Is API Key valid: Confirm API Key status at console.univer.ai
2. Is Univer instance running: Confirm Playground or local instance is running
3. Are session_ids consistent:

   univer_session_id in MCP configuration = sessionId in Univer instance

4. Network connection: Check if you can access mcp.univer.ai

Agent Side (MCP Client)

If basic connection is normal but still having issues, check:

• Does tool call return error messages? → Check specific error content
• Univer no response after tool execution? → Go to Univer instance side troubleshooting

Univer Instance Side

Check the following issues:

• Are all three MCP plugins registered?
• Is basic spreadsheet plugin (UniverSheetPlugin) enabled?
• Is permission configuration correct, has Univer instance successfully connected to MCP Server?
• Are there errors in browser console?
• Does univer_session_id strictly match the Agent side?

Security and Best Practices

• Do not use default as sessionId in production environment
• API Key should only be used on server side, not passed to browser side. Browser side authentication needs to obtain temporary credentials through server side to ensure API Key is not exposed

Next Steps

• Want to self-host MCP Server? Follow the progress of univer-mcp-start-kit
• Quick start: Use MCP Playground for online experience
• Complete guide: Check MCP Documentation Guide
• Having issues? Provide: sessionId, Agent type, error logs, Univer version

Supported MCP Tools

Univer MCP automatically provides 30+ spreadsheet operation tools, mainly including:

• Data Operations: Set and read cell data, search content, auto-fill, etc.
• Worksheet Management: Create, delete, rename worksheets, etc.
• Structure Operations: Insert/delete rows and columns, merge cells, adjust dimensions, etc.
• Format & Styling: Apply cell styles, conditional formatting, etc.
• Data Validation: Add and manage data validation rules, etc.

For detailed tool list, please refer to Start Kit Documentation.

Frequently Asked Questions (FAQ)

Q1: Why does it prompt "session occupied" after refreshing the page?

A: sessionId defaults to 'default', and each sessionId can only be connected by one client at a time.

Solution: Generate unique ID for each user or instance, for example:

sessionId: `user-${userId}`
// Or temporary solution
sessionId: `temp-${Date.now()}-${Math.random().toString(36).slice(2)}`

Q2: Agent can see tool list, but Univer doesn't respond when executing, console shows UniverAPI not available error?

A: Current version of Univer MCP depends on window.univerAPI to work.

For detailed integration steps, please refer to the complete example in univer-mcp-start-kit.

Q3: Why must UniverSheetPlugin and other plugins be registered? Can't I just register MCP plugins?

A: UniverSheetMCPPlugin itself doesn't contain spreadsheet operation capabilities, it only maps MCP tools to Univer API. The actual getRange(), setValue() and other functions are provided by UniverSheetPlugin.

Solution: Basic plugins must be registered first, otherwise tool execution will fail.

Q4: How do I know if MCP Server received LLM instructions? How to debug?

A:

• Backend (Cloud Service): https://console.univer.ai logs page can access all MCP call logs
• Network: Check WebSocket messages in browser DevTools Network → WS

Q5: Where to get API Key? How do Claude Pro users use it?

A:

• Apply for API Key at https://console.univer.ai
• All MCP clients (including Claude, Cursor, OpenAI) pass through HTTP Header:

Authorization: Bearer YOUR_API_KEY

• It has nothing to do with whether you use Claude CLI, Pro users can use it the same way.

Q6: Are MCP tools automatically provided? Do I need to write handlers for set_range_data myself?

A: No need. As long as UniverSheetMCPPlugin is correctly registered, it will automatically register 30+ built-in spreadsheet tools (such as set_range_data, insert_rows, etc.), and MCP Server will directly call Univer internal API for execution. You don't need to implement handlers manually.