A powerful Model Context Protocol (MCP) server for OpenBullet 2 that enables AI coding assistants to interact with OpenBullet 2 instances through natural language.
Connect your favorite AI IDE (Cursor, Claude Code, Cline, Windsurf) directly to OpenBullet 2 for intelligent automation, configuration generation, and job management.
- AI-Native Integration — Write and manage OpenBullet 2 configs using natural language through your favorite AI IDE
- Complete API Coverage — 30+ tools covering server management, configs, jobs, hits, proxies, wordlists, and more
- Built-in LoliCode Reference — AI assistants have comprehensive syntax documentation to write correct configs automatically
- Zero Configuration for Basic Use — Works with default OpenBullet 2 installations
- Multi-IDE Support — Compatible with Cursor, Claude Code, Cline, Windsurf, and any MCP-compliant client
- Node.js >= 18.0.0
- OpenBullet 2 Web instance (running on localhost:5000 by default)
git clone https://github.com/imwithyourbitch/openbullet2-mcp.git
cd openbullet2-mcp
npm install
npm run buildAdd to your IDE's MCP configuration file:
{
"mcpServers": {
"openbullet2": {
"command": "node",
"args": ["/absolute/path/to/openbullet2-mcp/dist/index.js"],
"env": {
"OB2_URL": "http://localhost:5000",
"OB2_USERNAME": "admin",
"OB2_PASSWORD": "admin"
}
}
}
}Add the server to your Cline MCP configuration with the same structure above.
Refer to your IDE's MCP setup documentation and use the configuration above.
Once configured, you can ask your AI assistant:
- "Create an OpenBullet 2 config that checks email:password combos against Gmail"
- "Start a proxycheck job and show me the results"
- "List all my wordlists and create a new one with 1000 entries"
- "Debug this config — it's not parsing correctly"
- LoliCode Syntax Reference — Comprehensive documentation built-in so AI assistants know correct block syntax, setting values, and config structure
- MCP Resources — Exposes syntax reference, quick cheat-sheet, and config creation guide as MCP resources
- MCP Prompts — Pre-built prompts for writing configs, editing configs, and full workflows
- Health checks and server info
- Collection statistics
- Announcements and update checks
- System, environment, RuriLib, and OpenBullet settings
- Create, read, update, delete LoliCode/C# configs
- Debug and test configs
- Convert between LoliCode, C#, and Stack formats
- Get block descriptors and code snippets
- Full LoliCode syntax reference access
- Create MultiRun and ProxyCheck jobs
- Start, stop, pause, resume, and abort jobs
- Change bot count dynamically
- View detailed bot statistics and status
- List and filter hits with multiple formats
- Delete hits and purge duplicates
- Send hits to recheck queue
- Export hits in various formats
- List and add proxies
- Manage proxy groups
- Delete and move proxies
- Import proxies from remote URLs
- List, preview, and create wordlists
- Update and delete wordlists
- Monitor wordlist statistics
- Create and delete guest user accounts
- Manage guest passwords
- Control guest access levels
- Plugin management
- Shared endpoint configuration
- Job monitoring with automated triggers
- Debug tools (garbage collection, log downloads)
Create a .env file in the project root to customize connection settings:
# Required
OB2_URL=http://localhost:5000
# Optional (if your OB2 instance requires authentication)
OB2_USERNAME=admin
OB2_PASSWORD=adminNote: If your OpenBullet 2 instance has no authentication configured, only OB2_URL is required.
openbullet2-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── config.ts # Environment configuration
│ ├── lolicode-reference.ts # Comprehensive LoliCode syntax reference
│ ├── resources.ts # MCP resources (syntax docs, guides)
│ ├── prompts.ts # MCP prompts (config workflows)
│ ├── client/
│ │ ├── ob2-client.ts # HTTP client with JWT authentication
│ │ └── types.ts # OpenBullet 2 API type definitions
│ ├── tools/
│ │ ├── server.ts # Server management tools
│ │ ├── configs.ts # Config management + syntax reference
│ │ ├── jobs.ts # Job management tools
│ │ ├── hits.ts # Hit management tools
│ │ ├── proxies.ts # Proxy management tools
│ │ ├── wordlists.ts # Wordlist management tools
│ │ ├── guests.ts # Guest management tools
│ │ ├── settings.ts # Settings management tools
│ │ ├── admin.ts # Admin tools
│ │ └── debug.ts # Debug tools
│ └── utils/
│ └── helpers.ts # Utility functions
├── package.json
├── tsconfig.json
├── .env.example
└── README.md
# Install dependencies
npm install
# Development with hot reload
npm run dev
# Type checking
npm run typecheck
# Build for production
npm run build
# Run built version
npm startThe MCP server includes comprehensive LoliCode syntax documentation so AI assistants connected to it can write correct OpenBullet 2 configs automatically.
Use the ob2_lolicode_reference tool to get:
- Full syntax reference
- Quick cheat-sheet
- Config creation guide
ob2://lolicode/syntax-reference— Complete LoliCode syntaxob2://lolicode/quick-reference— Quick reference guideob2://guides/config-creation— Step-by-step config creation
write-lolicode-config— Write a new config from scratchedit-lolicode-config— Modify an existing configcreate-config-workflow— Full workflow for complex configslolicode-syntax-help— Get syntax help for specific blocks
- Block syntax (
BLOCK:Name ... ENDBLOCK) - Common blocks (HttpRequest, Parse, Keycheck, Regex, etc.)
- Setting value types (fixed, variable
@name, interpolated$"<name>") - Keycheck/keychain condition syntax
- Flow control (IF/ELSE/WHILE/FOREACH/TRY/CATCH)
- Input data variables (
input.USER,input.PASS,data.SOURCE,data.STATUS) - Complete config examples with full JSON structure
- Config creation workflow (step-by-step)
- Cursor — Full support
- Claude Code — Full support
- Cline — Full support
- Windsurf — Full support
- Any MCP-compliant client — Supported
Ask your AI: "Create a LoliCode config that checks email:password combos against Gmail using IMAP"
The assistant can now:
- Write the complete config with correct LoliCode syntax
- Reference the built-in syntax guide
- Test the config before deployment
- Debug any issues
Ask your AI: "Load my proxies, create a proxycheck job, and run it with 50 bots"
The assistant can:
- List your existing proxies
- Create a new ProxyCheck job
- Configure bot count and settings
- Monitor job progress
Ask your AI: "Create a wordlist with common passwords and upload it"
The assistant can:
- Generate wordlist content
- Create it in OpenBullet 2
- Verify the upload
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Additional tools and features
- Bug fixes and improvements
- Documentation and examples
- Integration guides for other AI IDEs
- Performance optimizations
MIT License — See LICENSE file for details
Error: Cannot connect to OpenBullet 2
- Verify OpenBullet 2 is running on the configured URL
- Check
OB2_URLenvironment variable - Ensure your firewall allows the connection
Error: Authentication failed
- Verify
OB2_USERNAMEandOB2_PASSWORDare correct - If OB2 has no authentication, remove these variables from
.env
Error: Tool 'xyz' not found
- Ensure your IDE's MCP configuration points to the built
dist/index.js - Rebuild the project:
npm run build - Restart your IDE
- Open an issue for bug reports
- Start a discussion for feature requests
- Check existing issues before posting
Made with ❤️ for the OpenBullet and AI automation communities