WebMCP Documentation - AI-Powered Web Tools

The MCP-B extension includes a built-in userscript manager that lets you create, organize, and share custom scripts for any website. This guide covers everything you need to know about managing your userscripts.

What Are Userscripts?

Userscripts are JavaScript programs that run automatically on specific websites. They can:

Modify how websites look (themes, layouts, fonts)
Add new features (buttons, shortcuts, tools)
Remove unwanted elements (ads, popups, banners)
Automate repetitive tasks (form filling, data extraction)
Expose website functionality to AI agents (WebMCP servers)

All userscripts run locally in your browser. They only affect your view of websites - not other users’.

Accessing the Userscript Manager

Open the extension

Click the MCP-B icon in your browser toolbar

Navigate to Scripts

Click on the “Scripts” or “Userscripts” tab in the extension interface

View your scripts

You’ll see a list of all installed userscripts with their status

Creating Userscripts

Using an AI Agent

The easiest way to create userscripts is by asking an AI agent:

Userscript Engineer
WebMCP Server

Select the agent

Switch to “Userscript Engineer” in the agent dropdown

Describe what you want

“Add a dark mode toggle to reddit.com” or “Remove ads from news.ycombinator.com”

Review and test

The agent will create, test, and refine the script

Save

Once satisfied, the agent will commit the script to your library

Manual Creation

For advanced users, you can write userscripts manually:

Open the script editor

Click “New Script” in the userscript manager

Write your code

Use TypeScript or JavaScript. No userscript header required.

Configure metadata

Set which URLs the script should run on (matches pattern)

Test

Use the “Execute” button to test on the current page

Save

Click “Commit” to save permanently

Downloading Userscripts

Export Individual Scripts

Select the script

Click on the userscript you want to download

Open menu

Click the three dots (⋯) or “Actions” button

Export

Select “Download” or “Export”

Save file

Save the .ts or .js file to your computer

Export All Scripts

Open settings

Click the settings icon in the userscript manager

Export library

Select “Export All Scripts”

Save backup

Save the JSON file containing all your scripts

Regular backups are recommended, especially for critical automation scripts.

Uploading Userscripts

Import Individual Scripts

Open import dialog

Click “Import Script” or the upload icon (⬆) in the userscript manager

Select file

Choose a .ts, .js, or .user.js file from your computer

Review metadata

Check the script name and URL patterns

Confirm

Click “Import” to add the script to your library

Import Script Library

Open settings

Click the settings icon in the userscript manager

Import library

Select “Import Scripts”

Select JSON file

Choose the backup file you previously exported

Choose merge behavior

Decide whether to replace existing scripts or merge

Confirm

Click “Import” to restore your scripts

Always review scripts from untrusted sources before importing. Malicious scripts can access your browsing data or perform unwanted actions.

Using Userscripts

Enable/Disable Scripts

Individual Scripts
All Scripts

Toggle the switch next to each script to enable or disable it. Changes take effect immediately on matching pages.

Reload After Changes

When you modify or enable a userscript:

Refresh the page

The script won’t run on already-loaded pages until you refresh

Verify it's working

Check that the expected changes appear

Check console if needed

Open browser DevTools (F12) to see any error messages

Updating Scripts

Via Agent
Manual Edit

Open a chat, mention the script name, and describe the changes you want. The agent will update the script for you.

Organizing Scripts

Naming Convention

Use clear, descriptive names:

Good Names

github-dark-mode
reddit-hide-sidebar
amazon-price-tracker

Avoid

script1
test
untitled

URL Patterns

Configure which sites each script runs on:

// Run on all GitHub pages
matches: ["https://github.com/*"]

// Run on multiple domains
matches: ["https://reddit.com/*", "https://old.reddit.com/*"]

// Run on all sites (use sparingly)
matches: ["<all_urls>"]

// Run on specific subdomain
matches: ["https://news.ycombinator.com/*"]

Be specific with URL patterns. Overly broad patterns (like *://*/*) can slow down browsing and create security risks.

Publish to Community

Share your best scripts with the community:

GitHub Gist

Post your script as a Gist for easy sharing

Discord

Share in the WebMCP Discord #userscripts channel

Examples Repo

Submit a PR to the official examples repository

Social Media

Tweet about your creation with #WebMCP

Installation Instructions for Others

When sharing a script, include these steps:

## Installation

Install the [MCP-B Extension](https://chromewebstore.google.com/detail/mcp-b-extension/daohopfhkdelnpemnhlekblhnikhdhfa)
Open the extension and go to "Scripts"
Click "Import Script"
Select this file
Navigate to [website] to see it in action

Troubleshooting

Script not running

Possible causes:

Script is disabled (check the toggle)
URL pattern doesn’t match current page
Page needs to be refreshed
Script has JavaScript errors

Solution: Check script status, verify URL pattern, refresh page, and check browser console for errors.

Script conflicts with website

Possible causes:

Script selectors clash with site’s JavaScript
Script modifies elements the site depends on
Multiple scripts affecting the same elements

Solution: Disable other scripts one by one to identify conflicts. Ask an agent to refine the script to avoid conflicts.

Import fails

Possible causes:

File format not recognized
Malformed JSON in backup file
Script has syntax errors

Solution: Verify file extension (.ts, .js, .user.js, or .json). For JSON backups, validate the JSON structure. For scripts, check for syntax errors.

Script works then stops working

Possible causes:

Website updated and changed their HTML structure
Selectors no longer match elements
Website added anti-automation measures

Solution: Ask an agent to inspect the current page structure and update the script’s selectors.

Performance issues

Possible causes:

Too many scripts running simultaneously
Script has infinite loops or memory leaks
Script runs on too many sites

Solution: Disable scripts you’re not using. Review URL patterns to be more specific. Ask an agent to optimize the script.

Best Practices

Test in Private Window

Test scripts in incognito/private mode to ensure they work without other extensions interfering

Use Version Control

Export scripts regularly and keep versions so you can roll back if needed

Comment Your Code

Add comments explaining what each section does for future reference

Start Small

Build simple scripts first, then add complexity as needed

Use Stable Selectors

Target elements by ID or data attributes rather than generated class names

Handle Errors Gracefully

Add checks for missing elements and provide fallback behavior

Advanced Features

Script Execution Timing

Control when your script runs:

document_start
document_end
document_idle

Runs as soon as possible, before page loads. Good for blocking content or modifying page behavior early.

Script World

Choose where the script executes:

MAIN
ISOLATED

Runs in the page’s context with full access to page JavaScript. Required for MCP servers.

Using Web Standard APIs

WebMCP servers use the W3C Web Model Context API (navigator.modelContext) - global helpers and Zod are available:

import { z } from 'zod';

// Helper functions available globally in userscripts
const { formatSuccess, formatError, waitForSelector } = window.mcpHelpers;

// Register a tool using web standard API
navigator.modelContext.registerTool({
  name: 'tool_name',
  description: 'What this tool does',
  // Zod schemas are preferred for better type safety!
  inputSchema: {
    param: z.string().describe('Parameter description')
  },
  async execute({ param }) {
    // Tool logic here
    return formatSuccess('Success message', { data: 'result' });
  }
});

Zod Support: The web standard API accepts Zod schemas (preferred) as well as traditional JSON Schema. Zod provides better TypeScript integration, validation, and developer experience.

Security Considerations

Userscripts have significant power over websites you visit. Follow these security guidelines:

Only install trusted scripts

Review code before importing scripts from others. Malicious scripts can steal passwords, track activity, or perform unwanted actions.

Limit URL patterns

Don’t use <all_urls> unless absolutely necessary. Restrict scripts to specific domains they need.

Avoid storing sensitive data

Don’t hardcode passwords, API keys, or personal information in scripts. Use browser storage APIs with caution.

Keep scripts updated

Regularly review and update scripts to ensure they still work correctly and securely.

Use HTTPS

Only run scripts on HTTPS sites when possible to prevent man-in-the-middle attacks.

Examples and Templates

Examples Repository

Browse tested userscript examples for common tasks

WebMCP Playground

See WebMCP servers in action on a demo site

Discord Community

Get help and share scripts with other users

Extension Tools API

Technical reference for userscript management APIs

Quick Reference

Common Tasks

Create
Enable/Disable
Edit
Download
Upload
Delete

Ask Userscript Engineer or WebMCP Server agent → Describe what you want → Agent builds and tests → Script is saved

Next Steps

Try creating a simple script

Ask the Userscript Engineer to add a dark mode to your favorite website

Learn about agents

Read the Understanding Agents guide to choose the right agent for each task

Explore examples

Check out the Examples Repository for inspiration

Join the community

Share your creations on Discord

Getting Started

Core Features

Architecture & Development

​What Are Userscripts?

​Accessing the Userscript Manager

​Creating Userscripts

​Using an AI Agent

​Manual Creation

​Downloading Userscripts

​Export Individual Scripts

​Export All Scripts

​Uploading Userscripts

​Import Individual Scripts

​Import Script Library

​Using Userscripts

​Enable/Disable Scripts

​Reload After Changes

​Updating Scripts

​Organizing Scripts

​Naming Convention

Good Names

Avoid

​URL Patterns

​Categories

​Sharing Userscripts

​Export for Sharing

​Publish to Community

GitHub Gist

Discord

Examples Repo

Social Media

​Installation Instructions for Others

​Troubleshooting

​Best Practices

Test in Private Window

Use Version Control

Comment Your Code

Start Small

Use Stable Selectors

Handle Errors Gracefully

​Advanced Features

​Script Execution Timing

​Script World

​Using Web Standard APIs

​Security Considerations

​Examples and Templates

Examples Repository

WebMCP Playground

Discord Community

Extension Tools API

​Quick Reference

​Common Tasks

​Next Steps

What Are Userscripts?

Accessing the Userscript Manager

Creating Userscripts

Using an AI Agent

Manual Creation

Downloading Userscripts

Export Individual Scripts

Export All Scripts

Uploading Userscripts

Import Individual Scripts

Import Script Library

Using Userscripts

Enable/Disable Scripts

Reload After Changes

Updating Scripts

Organizing Scripts

Naming Convention

URL Patterns

Categories

Sharing Userscripts

Export for Sharing

Publish to Community

Installation Instructions for Others

Troubleshooting

Best Practices

Advanced Features

Script Execution Timing

Script World

Using Web Standard APIs

Security Considerations

Examples and Templates

Quick Reference

Common Tasks

Next Steps