The server provides discovery tools that allow agents to explore available categories and dynamically activate only the tools they need. This keeps the initial tool list small — preventing token bloat — while still giving agents access to the full platform on demand.

Tool visibility changes are per-session: each connected client has its own active toolset. Multiple agents can connect simultaneously and independently activate different tools without interfering with each other.

Installation & Usage

pip install openbb-mcp-server

Start the OpenBB MCP server with default settings:

openbb-mcp

Or use the uvx command:

uvx --from openbb-mcp-server --with openbb openbb-mcp

Command Line Options

Enter openbb-mcp --help to see the docstring from the command line.

--help
    Show this help message and exit.

--app <app_path>
    The path to the FastAPI app instance. This can be in the format
    'module.path:app_instance' or a file path 'path/to/app.py'.
    If not provided, the server will run with the default built-in app.

--name <name>
    The name of the FastAPI app instance or factory function in the app file.
    Defaults to 'app'.

--factory
    If set, the app is treated as a factory function that will be called
    to create the FastAPI app instance.

--host <host>
    The host to bind the server to. Defaults to '127.0.0.1'.
    This is a uvicorn argument.

--port <port>
    The port to bind the server to. Defaults to 8000.
    This is a uvicorn argument.

--transport <transport>
    The transport mechanism to use for the MCP server.
    Defaults to 'streamable-http'.

--allowed-categories <categories>
    A comma-separated list of tool categories to allow.
    If not provided, all categories are allowed.

--default-categories <categories>
    A comma-separated list of tool categories to be enabled by default.
    Defaults to 'all'.

--tool-discovery
    If set, tool discovery will be enabled.

--system-prompt <path>
    Path to a TXT file with the system prompt.

--server-prompts <path>
    Path to a JSON file with a list of server prompts.

All other arguments will be passed to `uvicorn.run`.

Configuration

The server can be configured through multiple methods, with settings applied in the following order of precedence:

Command Line Arguments: Highest priority, overriding all other methods.
Environment Variables: Each setting can be controlled by an environment variable, which will override the configuration file.
Configuration File: A JSON file at ~/.openbb_platform/mcp_settings.json provides the base configuration.

If the configuration file does not exist, one will be populated with the defaults.

Note: For some data providers you need to set your API key in the ~/.openbb_platform/user_settings.json file.

Authentication

The MCP server supports client-side and server-side authentication to secure your endpoints.

Server-Side Authentication

Server-side authentication requires incoming requests to provide credentials. This is configured using the server_auth setting, which accepts a tuple of (username, password).

When server_auth is enabled, clients must include an Authorization header with a Bearer token. The token should be a Base64-encoded string of username:password.

Example: Environment Variable

OPENBB_MCP_SERVER_AUTH='["myuser", "mypass"]'

Example: mcp_settings.json

{
  "server_auth": ["myuser", "mypass"]
}

Client-Side Authentication

Client-side authentication configures the MCP server to use credentials when making downstream requests. This is useful when the server needs to authenticate with other services.

Example: Environment Variable

OPENBB_MCP_CLIENT_AUTH='["client_user", "client_pass"]'

Example: mcp_settings.json

{
  "client_auth": ["client_user", "client_pass"]
}

Programmatic Authentication

For advanced use cases, you can pass a pre-configured authentication object directly to the create_mcp_server function using the auth parameter. This allows you to implement custom authentication logic or use third-party authentication providers.

from fastmcp.server.auth.providers import BearerProvider
from openbb_mcp_server.app import create_mcp_server

# Create a custom auth provider
custom_auth = BearerProvider(...)

# Pass it to the server
mcp_server = create_mcp_server(settings, fastapi_app, auth=custom_auth)

Advanced Configuration: Lists and Dictionaries

For settings that accept a list or a dictionary, you have two flexible formats for defining them in both command-line arguments and environment variables.

1. Comma-Separated Strings

This is a simple and readable way to define lists and simple dictionaries.

Lists: Provide a string of comma-separated values.
- Example: equity,news,crypto
Dictionaries: Provide a string of comma-separated key:value pairs.
- Example: host:0.0.0.0,port:9000

2. JSON-Encoded Strings

For more complex data structures, or to ensure precise type handling (e.g., for numbers and booleans), you can use a JSON-encoded string.

Lists: A standard JSON array.
- Example: '["equity", "news", "crypto"]'
Dictionaries: A standard JSON object.
- Example: '{"host": "0.0.0.0", "port": 9000}'

Important Note on Quoting: When passing JSON-encoded strings on the command line, it is highly recommended to wrap the entire string in single quotes ('). This prevents your shell from interpreting the double quotes (") inside the JSON string, which can lead to parsing errors.

Practical Examples

Here’s how you can apply these formats in practice:

Command-Line Arguments:

# List with comma-separated values
openbb-mcp --default-categories equity,news

# List with a JSON-encoded string (note the single quotes)
openbb-mcp --default-categories '["equity", "news"]'

# Dictionary with comma-separated key:value pairs
openbb-mcp --uvicorn-config "host:0.0.0.0,port:9000"

# Dictionary with a JSON-encoded string (note the single quotes)
openbb-mcp --uvicorn-config '{"host": "0.0.0.0", "port": 9000, "env_file": "./path_to/.env"}'

Environment Variables (in a .env file):

# List with comma-separated values
OPENBB_MCP_DEFAULT_TOOL_CATEGORIES="equity,news"

# List with a JSON-encoded string
OPENBB_MCP_DEFAULT_TOOL_CATEGORIES='["equity", "news"]'

# Dictionary with comma-separated key:value pairs
OPENBB_MCP_UVICORN_CONFIG="host:0.0.0.0,port:9000"

# Dictionary with a JSON-encoded string
OPENBB_MCP_UVICORN_CONFIG='{"host": "0.0.0.0", "port": 9000, "env_file": "./path_to/.env"}'

Settings Reference

All settings in the MCPSettings model can be configured via the mcp_settings.json file or as environment variables.

Setting	Environment Variable	Type	Default	Description
`api_prefix`	`OPENBB_MCP_API_PREFIX`	string	`None`	Overrides the API prefix from SystemService.
`name`	`OPENBB_MCP_NAME`	string	`"OpenBB MCP"`	Server name.
`description`	`OPENBB_MCP_DESCRIPTION`	string		Server description.
`version`	`OPENBB_MCP_VERSION`	string	`None`	Server version.
`instructions`	`OPENBB_MCP_INSTRUCTIONS`	string	`None`	Server instructions sent during the MCP `initialize` handshake. Auto-populated from system prompt if not set.
`default_tool_categories`	`OPENBB_MCP_DEFAULT_TOOL_CATEGORIES`	list[string]	`["all"]`	Default active tool categories on startup.
`allowed_tool_categories`	`OPENBB_MCP_ALLOWED_TOOL_CATEGORIES`	list[string]	`None`	Restricts available tool categories to this list.
`enable_tool_discovery`	`OPENBB_MCP_ENABLE_TOOL_DISCOVERY`	boolean	`False`	Enable per-session tool discovery (admin tools for browse/activate/deactivate).
`list_page_size`	`OPENBB_MCP_LIST_PAGE_SIZE`	integer	`None`	Max items per page in MCP list responses. `None` disables pagination.
`describe_responses`	`OPENBB_MCP_DESCRIBE_RESPONSES`	boolean	`False`	Include response types in tool descriptions.
`system_prompt_file`	`OPENBB_MCP_SYSTEM_PROMPT_FILE`	string	`None`	Path to a text file for the system prompt.
`server_prompts_file`	`OPENBB_MCP_SERVER_PROMPTS_FILE`	string	`None`	Path to a JSON file with a list of server prompt definitions.
`default_skills_dir`	`OPENBB_MCP_DEFAULT_SKILLS_DIR`	string	(bundled skills dir)	Path to a directory of bundled skill files. Set to `null` to disable.
`skills_reload`	`OPENBB_MCP_SKILLS_RELOAD`	boolean	`False`	Reload skill files on every read (useful during development).
`skills_providers`	`OPENBB_MCP_SKILLS_PROVIDERS`	list[string]	`None`	Vendor skill provider short-names to load (e.g. `["claude", "cursor"]`).
`cache_expiration_seconds`	`OPENBB_MCP_CACHE_EXPIRATION_SECONDS`	float	`None`	Cache expiration time in seconds. `0` to disable.
`on_duplicate_tools`	`OPENBB_MCP_ON_DUPLICATE_TOOLS`	string	`None`	Behavior for duplicate tools (`warn`, `error`, `replace`, `ignore`).
`on_duplicate_resources`	`OPENBB_MCP_ON_DUPLICATE_RESOURCES`	string	`None`	Behavior for duplicate resources.
`on_duplicate_prompts`	`OPENBB_MCP_ON_DUPLICATE_PROMPTS`	string	`None`	Behavior for duplicate prompts.
`resource_prefix_format`	`OPENBB_MCP_RESOURCE_PREFIX_FORMAT`	string	`None`	Format for resource URI prefixes (`protocol` or `path`).
`mask_error_details`	`OPENBB_MCP_MASK_ERROR_DETAILS`	boolean	`None`	Mask error details from user functions.
`dependencies`	`OPENBB_MCP_DEPENDENCIES`	list[string]	`None`	List of dependencies to install.
`module_exclusion_map`	`OPENBB_MCP_MODULE_EXCLUSION_MAP`	dict[str, str]	`None`	Map API tags to Python module names for exclusion.
`uvicorn_config`	`OPENBB_MCP_UVICORN_CONFIG`	dict	`{"host": "127.0.0.1", "port": "8001"}`	Configuration for the Uvicorn server.
`httpx_client_kwargs`	`OPENBB_MCP_HTTPX_CLIENT_KWARGS`	dict	`{}`	Configuration for the async httpx client.
`client_auth`	`OPENBB_MCP_CLIENT_AUTH`	tuple[string, string]	`None`	`(username, password)` for client-side basic authentication (passed-through to HTTPX).
`server_auth`	`OPENBB_MCP_SERVER_AUTH`	tuple[string, string]	`None`	`(username, password)` for server-side basic authentication.

Note: Runtime argument keys, in general, "-" and "_" are interchangeable. Nested uvicorn arguments should use _.

Tool Categories

The server organizes OpenBB tools into categories based on the included API Routers (paths). Categories depend on the installed extensions, but will be the first path in the API after the given prefix.

For example:

equity - Stock data, fundamentals, price history, estimates
crypto - Cryptocurrency data and analysis
economy - Economic indicators, GDP, employment data
news - Financial news from various sources
fixedincome - Bond data, rates, government securities
derivatives - Options and futures data
etf - ETF information and holdings
currency - Foreign exchange data
commodity - Commodity prices and data
index - Market indices data
regulators - SEC, CFTC regulatory data

Each category contains subcategories that group related functionality (e.g., equity_price, equity_fundamental, etc.).

Root Tools

An additional set of tools are tagged as "admin", or "prompt".

available_categories: List all tool categories with subcategory names and tool counts.
available_tools: List tools in a specific category (and optional subcategory).
- category: Category of tools to list.
- subcategory: Optional subcategory. Use general for tools directly under the category.
- Inactive tools still show a short description so they remain discoverable.
activate_tools: Activate one or more tools by name for this session.
- tool_names: List of tool names to activate.
deactivate_tools: Deactivate one or more tools by name for this session.
- tool_names: List of tool names to deactivate.
activate_category: Activate all tools in a category (or subcategory) at once.
- category: Category name.
- subcategory: Optional subcategory to narrow the activation.
list_prompts: Lists all available prompts in the server.
execute_prompt: Execute a prompt with arguments, if any.
- prompt_name: Name of the prompt to execute.
- arguments: Dictionary of argument:value for the prompt.

Tool Discovery

When enable_tool_discovery is enabled, the server registers a small set of admin tools that let agents progressively discover and activate what they need:

Browse — available_categories returns the category tree with tool counts.
Inspect — available_tools lists every tool in a category with its active/inactive state and a short description.
Activate — activate_tools or activate_category enables specific tools (or an entire category) for the current session.
Deactivate — deactivate_tools removes tools when they are no longer needed.

All visibility changes are per-session — each client maintains its own active toolset, so the server is safe for multi-user deployments.

To take full advantage of minimal startup tools, set --default-categories admin so only the discovery tools are active on connect.

For scenarios where you want discovery available, enable it with --tool-discovery. Otherwise the server runs with a fixed toolset and you can control the available tools via allowed_tool_categories and default_tool_categories.

System Prompt

A system prompt file can be added on initialization, or defined in the configuration file, or as an environment variable. It should be a valid, relative or absolute, path to a .txt file.

The system prompt is made available as a resource, resource://system_prompt, and is discoverable from the, list_prompts, tool.

Clients will not automatically use the system prompt, instruct them to use it as part of their onboarding and orientation.

Skills

The server ships with a set of bundled skill guides — Markdown documents that teach an agent how to perform complex multi-step tasks with the OpenBB Platform. Skills are exposed as MCP resources and are discoverable via list_resources().

Each skill is available at a URI of the form skill://<name>/SKILL.md.

Bundled Skills

Skill	URI	Description
`develop_extension`	`skill://develop_extension/SKILL.md`	Step-by-step guide for building an OpenBB Platform extension.
`build_workspace_app`	`skill://build_workspace_app/SKILL.md`	Guide for building and running OpenBB Workspace applications.
`configure_mcp_server`	`skill://configure_mcp_server/SKILL.md`	Reference for configuring and customising the OpenBB MCP Server.
`work_with_server`	`skill://work_with_server/SKILL.md`	Practical guide for working with the OpenBB MCP Server as an agent.

When any skills are loaded and no system_prompt_file is configured, the server automatically adds a brief default system prompt that nudges the agent to discover available skills.

Skill Settings

Setting	Description
`default_skills_dir`	Path to the bundled skills directory. Set to `null` or an empty string to disable loading the built-in skills.
`skills_reload`	Set to `true` to reload skill files from disk on every read — useful when authoring or iterating on skill content.
`skills_providers`	A list of vendor skill provider short-names. Supported values: `claude`, `cursor`, `vscode`, `copilot`, `codex`, `gemini`, `goose`, `opencode`.

Example — disable bundled skills:

{
  "default_skills_dir": null
}

Example — load vendor skill providers:

{
  "skills_providers": ["claude", "cursor"]
}

Example — enable skill reload during development:

OPENBB_MCP_SKILLS_RELOAD=true

Server Prompts

A system prompt file can be added on initialization, or defined in the configuration file, or as an environment variable. It should be a valid, relative or absolute, path to a .json file with a list of prompt definitions.

Each entry in the JSON file is a dictionary with the following properties:

name: Name of the prompt.
description: A brief description of the prompt.
content: The content for rendering the prompt.
arguments: Optional list of arguments.
- name: Name of the argument.
- type: Simple Python type as a string - i.e, "int".
- default: Supplying a default value makes the parameter Optional.
- description: Description of the parameter. Supply need-to-know details for the LLM.
tags: List of tags to apply to the argument.

Prompts here should provide the LLM a clear path for executing a workflow combining multiple tools or steps, for example:

[
    {
      "name": "equity_analysis",
      "description": "Perform a comprehensive equity analysis using multiple data sources and metrics",
      "content": "Conduct a comprehensive analysis of {symbol} for {analysis_period}. Follow this workflow:\n1. First, get basic stock quote and recent price performance using equity_price_performance.\n2. Retrieve fundamental data including financial statements, ratios, and key metrics using [equity_fundamental_ratios, equity_fundamental_metrics, quity_fundamental_balance].\n3. Gather recent news and analyst estimates for the company using [news_company, equity_estiments_price_target].\n4. Compare valuation metrics with industry peers using equity_compare_peers.\n5. Summarize findings with investment recommendation.\n\nFocus areas: {focus_areas}\nRisk tolerance: {risk_tolerance}",
      "arguments": [
        {
          "name": "symbol",
          "type": "str",
          "description": "Stock ticker symbol to analyze (e.g., AAPL, TSLA)"
        },
        {
          "name": "analysis_period",
          "type": "str",
          "default": "last 12 months",
          "description": "Time period for the analysis"
        },
        {
          "name": "focus_areas",
          "type": "str",
          "default": "growth, profitability, valuation",
          "description": "Specific areas to focus on in the analysis"
        },
        {
          "name": "risk_tolerance",
          "type": "str",
          "default": "moderate",
          "description": "Risk tolerance level: conservative, moderate, or aggressive"
        }
      ],
      "tags": ["equity", "analysis", "comprehensive"]
    }
]

An invalid prompt definition, or prompt argument, will be logged to the console as an error. The item will be ignored, and will not raise an error.

Inline Prompts

Prompts can be added to an endpoint through the openapi_extra dictionary.

Adding prompts here will help the LLM use the endpoint for specific purposes, with less reasoning overhead.

Direct it to execute_prompt, or to make note that helpful prompts may be included in the tool's metadata.

The block below assumes app is an instance of FastAPI

@app.get(
    "/economy/gdp",
    openapi_extra={
        "mcp_config": {
            "prompts": [
                {
                    "name": "gdp_summary_prompt",
                    "description": "Generate a brief summary of GDP for a country.",
                    "content": "Provide a concise summary of the GDP for {country} over the last {years} years.",
                    "arguments": [
                        {
                            "name": "years",
                            "type": "int",
                            "default": 5,
                            "description": "Number of years to summarize.",
                        }
                    ],
                    "tags": ["economy", "gdp", "summary"],
                },
                {
                    "name": "gdp_comparison_prompt",
                    "description": "Compare the GDP of two countries.",
                    "content": "Compare the GDP growth of {country1} and {country2}.",
                    "arguments": [
                        {
                            "name": "country1",
                            "type": "str",
                            "description": "First country for comparison.",
                        },
                        {
                            "name": "country2",
                            "type": "str",
                            "description": "Second country for comparison.",
                        },
                    ],
                    "tags": ["economy", "gdp", "comparison"],
                },
            ]
        }
    },
)
def get_gdp_data(country: str, period: Literal["annual", "quarterly"] = "annual"):
    """Get GDP data for a specific country."""
    return {"country": country, "period": period}

Along with being added to list_prompts, prompts will be included with the tool's metadata, returned by list_tools.

The discovery metadata for this tool would look like:

Economy Tools:

economy_gdp: Get GDP data for a specific country.
- Associated Prompts:
  - gdp_summary_prompt: Generate a brief summary of GDP for a country. (Arguments: years, country)
  - gdp_comparison_prompt: Compare the GDP of two countries. (Arguments: country1, country2)

Use a prompt with the execute_prompt tool:

{
  "prompt_name": "gdp_summary_prompt",
  "arguments": {
    "years": 10,
    "country": "Japan"
  }
}

Which outputs:

{
  "description": "Generate a brief summary of GDP for a country.",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Use the tool, economy_gdp, to perform the following task.\n\nProvide a concise summary of the GDP for Japan over the last 10 years."
      }
    }
  ]
}

Inline MCP Configuration

In addition to defining prompts, the openapi_extra.mcp_config dictionary allows for more granular control over how your FastAPI routes are exposed as MCP tools. By using the MCPConfigModel, you can validate your configuration and access several powerful properties to customize tool behavior.

It can be imported with:

from openbb_mcp_server.models.mcp_config import MCPConfigModel

Including this configuration in the openapi_extra slot will override any automatically generated value. You only need to enter the values that you wish to customize.

Below are the properties you can define within mcp_config:

expose (Optional[bool]): Set to False to completely hide a route from the MCP server. This is useful for internal or deprecated endpoints that should not be available as tools.
mcp_type (Optional[MCPType]): Classify the route as a specific MCP type. Valid options are "tool", "resource", or "resource_template".
methods (Optional[list[HTTPMethod]]): Specify which HTTP methods to expose for a route that supports multiple methods (e.g., GET, POST). If omitted, all supported methods are exposed. Valid methods include "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", and * (for all).
exclude_args (Optional[list[str]]): Provide a list of argument names to exclude from the tool’s signature. This is useful for filtering out parameters that are handled internally or are not relevant to the end-user.
prompts (Optional[list[dict[str, str]]]): List of prompts specific to the endpoint. Keys for a prompt are:
- name: Name of the prompt.
- description: A brief description of the prompt.
- content: The content for rendering the prompt. Endpoint parameters are inferred by placeholders.
- arguments: Optional list of arguments. Items can be exclusive to the prompt, and not referenced in the endpoint.
  - name: Name of the argument.
  - type: Simple Python type as a string - i.e, "int".
  - default: Supplying a default value makes the parameter Optional.
  - description: Description of the parameter. Supply need-to-know details for the LLM.
- tags: List of tags to apply to the argument.

MCPConfigModel Validation

Values will be validated by the model before including in the server. Invalid configurations will be logged to the console as an error, and the inline definition will be ignored.

ERROR    Invalid MCP config found in route, 'GET /equity/price'. Skipping tool customization because of validation error ->
          1 validation error for MCPConfigModel
          mcp_type
            Input should be 'tool', 'resource' or 'resource_template' [type=enum, input_value='some_setting', input_type=str]
              For further information visit https://errors.pydantic.dev/2.11/v/enum

Example

Here is an example demonstrating how to use these properties to fine-tune a tool’s behavior:

@app.get(
    "/some/route",
    openapi_extra={
        "mcp_config": {
            "expose": True,
            "mcp_type": "tool",
            "methods": ["GET"],
            "exclude_args": ["internal_param"],
            "prompts": [
                # ... prompt definitions ...
            ]
        }
    },
)
def some_route(param1: str, internal_param: str = "default"):
    """An example route with advanced MCP configuration."""
    return {"param1": param1}

In this example, the /some/route endpoint is explicitly exposed as a tool for the GET method only, and the internal_param argument is hidden from the tool’s interface.

Client Examples

Start the server with the appropriate transport and configuration for the client, the default transport is http.

# Start with default settings
openbb-mcp

# Use an alternative transport
openbb-mcp --transport sse

# Start with specific categories and custom host/port
openbb-mcp --default-categories equity,news --host 0.0.0.0 --port 8080

# Start with allowed categories restriction
openbb-mcp --allowed-categories equity,crypto,news

# Enable tool discovery for per-session activation
openbb-mcp --tool-discovery

Claude Desktop:

To connect the OpenBB MCP server with Claude Desktop, you need to configure it as a custom tool server. Here are the steps:

Locate the settings or configuration file for Claude Desktop where you can define custom MCP servers.
Add the following entry to your mcpServers configuration. This will configure Claude Desktop to launch the OpenBB MCP server automatically using stdio for communication.

{
  "mcpServers": {
    "openbb-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "openbb-mcp-server",
        "--with",
        "openbb",
        "openbb-mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

Ensure that uvx, is installed and available in your system's PATH. If not, follow the installation instructions.
Restart Claude Desktop to apply the changes. You should now see "openbb-mcp" as an available tool source.

Cursor:

To use OpenBB tools within Cursor, you first need to run the MCP server and then tell Cursor how to connect to it.

Step 1: Run the OpenBB MCP Server

Open your terminal and start the server. You can use the default settings or customize it.

For a default setup, run:

openbb-mcp

The server will start on http://127.0.0.1:8001.

Step 2: Configure Cursor

Add the following configuration to the mcpServers object in your mcp.json file. If the mcpServers object doesn't exist, you can add it.

{
  "mcpServers": {
    "openbb-mcp": {
      "url": "http://localhost:8001/mcp/"
    }
  }
}

VS Code

Step 1: Enable MCP in VS Code Settings

Enter shift + command + p and open "Preferences: Open User Settings"

Search for "mcp", and the item should show up under "Chat". Check the box to enable MCP server integrations.

Step 2: Run the OpenBB MCP Server