MCP Tools Reference
Complete reference for Blueberryās MCP (Model Context Protocol) tools.
Overview
Blueberry provides 10 MCP tools that AI coding agents can use to interact with your workspace. These tools give your AI visibility into your code, terminal, browser preview, and pinned apps.
Tools
Context
blueberry_get_context
Get the current IDE context organized by panel with visibility status.
Returns a structured object:
- project: Current project path
- editor: { isVisible, activeFile, openTabs, cursor, selection, diffView }
- terminal: { isVisible, tabs (with id/name for send-terminal-command) }
- preview: { isVisible, activeUrl, tabs (with id/url/title for screenshots) }
- pinnedApps: [{ id, url, title, isVisible }] - pinned web apps
- sidebar: { isVisible, activePanel }
Each section has āisVisibleā at the top so you know immediately whatās showing. Use this to understand what the user is currently working on before taking actions.
Parameters: None
Editor
blueberry_open_file
Open a file in the Blueberry code editor. Optionally jump to a specific line number.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path relative to project root (e.g., āsrc/components/Button.tsxā) |
line | number | No | Optional line number to scroll to |
Preview Browser
blueberry_open_preview
Open a URL in the Blueberry preview panel and switch to preview view. Use this to show the user a webpage or their running dev server. IMPORTANT: Always use newTab: true unless the user explicitly asks to replace the current tab - this preserves the userās existing tabs.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | URL to open (e.g., āhttp://localhost:3000/dashboardĀ ā) |
newTab | boolean | No | Open in a new tab instead of replacing current tab. Default to true to preserve existing tabs. |
blueberry_capture_webview_screenshot
Capture a screenshot of a preview tab or pinned web app. Returns a base64 PNG data URL. For preview tabs: check preview.isVisible is true first. For pinned apps: check the appās isVisible is true in pinnedApps. Only works in desktop mode (not browser/iPad).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
tabId | string | No | Preview tab ID to capture. If not specified, captures the active preview tab. Use blueberry_get_context to see available preview tabs. |
appId | string | No | Pinned app ID to capture (e.g., āapp-uuidā). Takes precedence over tabId. Use blueberry_get_context to see available pinnedApps. |
blueberry_capture_webview_content
Get the TEXT CONTENT of a preview tab or pinned web app. Returns the page content as a structured text representation (accessibility tree) showing headings, links, buttons, text, and hierarchy. Use this to READ whatās on the page - much more useful than screenshots when you need to know what the page says. For preview tabs: check preview.isVisible is true first. For pinned apps: check the appās isVisible is true.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
tabId | string | No | Preview tab ID to snapshot. If not specified, uses the active preview tab. |
appId | string | No | Pinned app ID to snapshot (e.g., āapp-uuidā). Takes precedence over tabId. Use blueberry_get_context to see available pinnedApps. |
blueberry_get_console_logs
Get console logs (log, warn, error, info, debug) from a preview tab. Logs are captured from console.log/warn/error calls in the previewed page. Buffer is cleared when the page reloads. Response includes available tabs with log counts.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
tabId | string | No | Preview tab ID to get logs from. If not specified, uses the active tab. See availableTabs in response for tab IDs. |
limit | number | No | Max number of logs to return (default: 50, max: 100) |
level | `āall" | "error" | "warn" |
clear | boolean | No | Clear the log buffer after reading (default: false). Useful for āwhatās new since last checkā pattern. |
Terminal
blueberry_send_terminal_command
Send a command to a terminal tab in Blueberry. Use blueberry_get_context first to see available terminals (terminal.tabs) and their IDs. Supports escape sequences: \x03 for Ctrl+C, \x04 for Ctrl+D, etc.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionId | string | Yes | Terminal session ID (get from blueberry_get_context terminal.tabs) |
command | string | Yes | Command to send. Use \x03 for Ctrl+C (interrupt), \x04 for Ctrl+D (EOF). Empty string just presses Enter. |
submit | boolean | No | Whether to auto-submit (press Enter). Default: true. Set to false for signals like Ctrl+C. (default: true) |
blueberry_create_terminal
Create a new terminal tab in Blueberry. Use blueberry_send_terminal_command to run commands in it.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | Name for the terminal tab (e.g., āDev Serverā, āTestsā) |
blueberry_get_terminal_logs
Get the output/logs from a terminal tab. Returns the last N lines of terminal output. Useful for debugging build errors, test failures, or seeing what commands produced. Use blueberry_get_context first to see available terminals (terminal.tabs) and their session IDs.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionId | string | No | Terminal session ID to get logs from. Get this from blueberry_get_context terminalTabs. If not specified, returns list of available terminals. |
limit | number | No | Max number of lines to return (default: 100, max: 500). Recent lines are returned first. |
Pinned Apps
blueberry_open_pinned_app
Open/show a pinned web app panel. Use blueberry_get_context to see available pinnedApps with their IDs and titles. This makes the pinned app panel visible if itās not already showing.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
appId | string | Yes | Pinned app ID to open (e.g., āapp-uuidā). Get available IDs from blueberry_get_context pinnedApps. |
Usage Notes
Running AI Agents in Blueberry
For an AI agent to access these tools, you must run it from a Blueberry terminal:
- Open a terminal tab in Blueberry
- Navigate to your project directory
- Start your agent (e.g.
claude,codex,gemini)
The agent will automatically have access to all MCP tools when started this way.
Best Practices
- Always call
blueberry_get_contextfirst to understand the current workspace state - Check
isVisibleflags before interacting with panels - Use
blueberry_capture_webview_contentinstead of screenshots when you need to read text - Prefer named terminal tabs for organization (e.g., āDev Serverā, āTestsā)
Error Handling
Tools may return errors in these situations:
- āBlueberry is not runningā - Start Blueberry and open your project
- āNot running in a Blueberry terminalā - Run your AI agent from a Blueberry terminal
- āNo context availableā - Open a project folder in Blueberry