Skip to main content
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

1

Open the extension

Click the MCP-B icon in your browser toolbar
2

Navigate to Scripts

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

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:
1

Select the agent

Switch to “Userscript Engineer” in the agent dropdown
2

Describe what you want

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

Review and test

The agent will create, test, and refine the script
4

Save

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

​
Manual Creation

For advanced users, you can write userscripts manually:
1

Open the script editor

Click “New Script” in the userscript manager
2

Write your code

Use TypeScript or JavaScript. No userscript header required.
3

Configure metadata

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

Test

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

Save

Click “Commit” to save permanently

​
Downloading Userscripts

​
Export Individual Scripts

1

Select the script

Click on the userscript you want to download
2

Open menu

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

Export

Select “Download” or “Export”
4

Save file

Save the .ts or .js file to your computer

​
Export All Scripts

1

Open settings

Click the settings icon in the userscript manager
2

Export library

Select “Export All Scripts”
3

Save backup

Save the JSON file containing all your scripts
Regular backups are recommended, especially for critical automation scripts.

​
Uploading Userscripts

​
Import Individual Scripts

1

Open import dialog

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

Select file

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

Review metadata

Check the script name and URL patterns
4

Confirm

Click “Import” to add the script to your library

​
Import Script Library

1

Open settings

Click the settings icon in the userscript manager
2

Import library

Select “Import Scripts”
3

Select JSON file

Choose the backup file you previously exported
4

Choose merge behavior

Decide whether to replace existing scripts or merge
5

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

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:
1

Refresh the page

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

Verify it's working

Check that the expected changes appear
3

Check console if needed

Open browser DevTools (F12) to see any error messages

​
Updating Scripts

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.

​
Categories

Group related scripts for easy management:
  • Productivity: Auto-fill forms, keyboard shortcuts
  • Appearance: Dark modes, custom themes, layout changes
  • Content: Ad blockers, element hiders
  • Automation: Data extraction, monitoring
  • MCP Servers: Scripts that expose website tools to AI

​
Sharing Userscripts

​
Export for Sharing

1

Download the script

Export the script you want to share
2

Share the file

Send the .ts or .js file to others
3

Include instructions

Explain what the script does and which sites it works on

​
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

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

​
Troubleshooting

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.
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.
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.
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.
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:
Runs as soon as possible, before page loads. Good for blocking content or modifying page behavior early.

​
Script World

Choose where the script executes:
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:
Review code before importing scripts from others. Malicious scripts can steal passwords, track activity, or perform unwanted actions.
Don’t use <all_urls> unless absolutely necessary. Restrict scripts to specific domains they need.
Don’t hardcode passwords, API keys, or personal information in scripts. Use browser storage APIs with caution.
Regularly review and update scripts to ensure they still work correctly and securely.
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

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

​
Next Steps

1

Try creating a simple script

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

Learn about agents

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

Explore examples

Check out the Examples Repository for inspiration
4

Join the community

Share your creations on Discord