OpenBB Widgets JSON MCP Server
An MCP server that exposes the OpenBB widgets.json specification as structured, callable tools. Instead of parsing long-form documentation, developers (and AI coding assistants like Claude Code) can directly query widget types, inputs, and configuration examples through this server.
What This Does
Each widget type is mapped to its own tool—making it easy to generate, mix, and match valid JSON specs when building new OpenBB apps. The server is built with FastMCP, programmatically generated from the OpenBB developer docs, and hosted on Smithery.ai for discoverability.
The server provides:
- Widget configuration and types documentation
- Widget parameters (dropdowns, date pickers, toggles, etc.)
- JSON specifications for widgets, apps, and agents
- Essential boilerplate code for building OpenBB widgets
- Data integration and AI agents documentation
Prerequisites
- Python 3.12 or higher
- uv package manager
- Node.js and npx (optional, for Smithery CLI and playground)
Quick Start
-
Clone the repository:
git clone https://github.com/OpenBB-finance/openbb-widgets-json-mcp.git cd openbb-widgets-json-mcp -
Install dependencies:
uv sync -
Run the server:
uv run python main.py -
Test it's working: The server will start on
http://localhost:8081 -
Launch Smithery Playground (optional):
npm install -g @smithery/cli smithery playground --port 8081This opens an interface to test the MCP tools interactively.
Available MCP Tools
Via iterating through OpenBB docs
Widget Configuration Tools
widget_configuration_category_subcategory- Category and subcategory configurationwidget_configuration_error_handling- Error handling in widgetswidget_configuration_grid_size- Grid size configurationwidget_configuration_refetch_interval- Refetch interval settingswidget_configuration_render_functions- Render functionswidget_configuration_run_button- Run button configurationwidget_configuration_stale_time- Stale time settings
Widget Parameter Tools
widget_parameters_text_input- Text input parameterswidget_parameters_date_picker- Date picker parameterswidget_parameters_boolean_toggle- Boolean toggle parameterswidget_parameters_dropdown- Dropdown parameterswidget_parameters_advanced_dropdown- Advanced dropdown parameterswidget_parameters_dependent_dropdown- Dependent dropdown parameterswidget_parameters_number_input- Number input parameterswidget_parameters_input_form- Input form parameterswidget_parameters_parameter_grouping- Parameter groupingwidget_parameters_parameter_positioning- Parameter positioningwidget_parameters_cell_click_grouping- Cell click grouping
Widget Type Tools
widget_types_plotly_charts- Plotly chartswidget_types_highcharts- Highchartswidget_types_tradingview_charts- TradingView chartswidget_types_aggrid_table_charts- AgGrid table chartswidget_types_markdown- Markdown widgetswidget_types_html- HTML widgetswidget_types_metric- Metric widgetswidget_types_newsfeed- Newsfeed widgetswidget_types_file_viewer- File viewer widgetswidget_types_live_grid- Live grid widgetswidget_types_omni- Omni widgetswidget_types_ssrm_mode- SSRM mode
JSON Reference Tools
json_specs_widgets_json_reference- Widgets JSON referencejson_specs_apps_json_reference- Apps JSON referencejson_specs_agents_json_reference- Agents JSON reference
Additional Tools
data_integration- Data source integrationai_agents_ai_agents- AI agents documentationapps_apps- OpenBB applications documentation
Added ad-hoc
building_widgets_on_openbb- Essential boilerplate code for OpenBB widgets (ALWAYS call this first)
Example: Playground Monte Carlo Widget
The playground/ folder contains a complete Monte Carlo simulation widget built using Claude Code and this MCP server. This demonstrates the full development workflow:
- Claude Code queried the MCP server for OpenBB widget specifications
- MCP tools provided boilerplate code, plotly chart documentation, and JSON reference specs
- Generated widget includes:
- 3 parameters: ticker (text), start_date (date), use_volatility_adjustment (boolean)
- Plotly visualization with 50 simulation paths + percentile bands
- Raw data mode returning pure simulation arrays
- Run button for manual execution
- Full OpenBB Workspace integration
To run the example:
cd playground
uv sync
uv run python main.py
This serves as a practical example of how AI coding assistants can leverage MCP servers to rapidly build compliant OpenBB widgets by accessing structured documentation programmatically.
Deploy to Smithery
To deploy your MCP server:
- Push your code to GitHub (include
smithery.yamlandDockerfile) - Connect your repository at https://smithery.ai/new
Your server will be available over HTTP and ready to use with any MCP-compatible client!
Stopping the Server
Press Ctrl+C in the terminal to stop the server.