openbb-finance/openbb/work-with-server

Claude Code and agent skill by openbb-finance/openbb

Trust tier 2
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

This guide explains how to call tools, interpret responses, discover capabilities, use prompts, and handle errors when interacting with an OpenBB MCP server.

Install

npx vskill@latest install openbb-finance/openbb/work-with-server

SKILL.md

The same SKILL.md was published earlier as openbb-finance/openbb/work-with-server.

Working With the OpenBB MCP Server

This guide explains how to call tools, interpret responses, discover capabilities, use prompts, and handle errors when interacting with an OpenBB MCP server.


Tool Discovery Workflow

When the server runs with --tool-discovery, the OpenBB tools are left out of the tool list, and a small set of discovery tools finds and runs them.

Discovery holds no per-session state — every client sees the same tool list, and nothing needs to be activated before a call.

Step 1 — List Categories

Call available_categories (no arguments) to see what is installed:

json
[
{
"name": "equity",
"subcategories": [
{"name": "price", "tool_count": 5},
{"name": "fundamental", "tool_count": 12}
],
"total_tools": 17
},
{
"name": "economy",
"subcategories": [
{"name": "general", "tool_count": 3}
],
"total_tools": 3
}
]

Each category maps to a top-level API router. Subcategories are nested routers.

Step 2 — Browse Tools in a Category

Call available_tools with a category name:

json
// Input
{"category": "equity", "subcategory": "price"}
// Output
[
{"name": "equity_price_historical", "description": "Get historical price data..."},
{"name": "equity_price_quote", "description": "Get current price quote..."}
]

Each entry has the tool's name and a one-sentence description. The subcategory argument is optional. Omit it to see all tools in the category.

Step 3 — Search for Tools

Call search_tools with a natural-language query:

json
// Input
{"query": "historical stock prices"}
// Output - full tool definitions, in the same format as list_tools
[
{"name": "equity_price_historical", "description": "...", "inputSchema": {"...": "..."}}
]

Search covers the hidden OpenBB tools and returns at most five matches. Use each match's inputSchema to build the arguments.

Step 4 — Call a Tool

Call call_tool with the tool name and its arguments:

json
{"name": "equity_price_historical", "arguments": {"symbol": "AAPL", "provider": "yfinance"}}

call_tool runs the named tool and returns its result. A hidden tool can also be called directly by name, with the same arguments.

When Discovery Is Disabled

If the server was started without --tool-discovery, the discovery tools are not available. All tools in default_tool_categories are listed and called directly; tools outside them are not served, and calling one fails with "Unknown tool".


openbb-cli Dispatcher Tools

When the optional openbb-mcp-server[cli] extra is installed (it pulls in openbb-cli), the server also registers four first-class tools that wrap openbb-cli's NDJSON dispatcher protocol. They give an agent the same obb-namespace command surface that the openbb CLI exposes — without shelling out or standing up a Python REPL.

openbb_dispatch

Execute a single command and return its serialized result.

json
{
"name": "openbb_dispatch",
"arguments": {
"command": "equity.price.historical",
"params": {"symbol": "AAPL", "provider": "yfinance"},
"server_url": null
}
}
ArgumentTypeNotes
commandstringDotted command path under the obb namespace (e.g. equity.price.historical).
params`dict \null`Keyword arguments forwarded to the command. Defaults to {}.
server_url`string \null`When set, dispatches against a remote openbb-platform-api server (HTTP). When omitted, falls back to OPENBB_SERVER_URL, then in-process local dispatch.

The result is a dispatcher response. ok reports success, result holds the command's OBBject fields (results, provider, ...), and error carries the type and message of a failure instead of raising:

json
{
"id": null,
"ok": true,
"result": {"results": [{"date": "2025-01-02", "close": 243.85}], "provider": "yfinance"},
"error": null
}

Remote dispatch unwraps a single-row results list to the row itself.

openbb_batch_dispatch

Execute many commands concurrently and return results in input order.

json
{
"name": "openbb_batch_dispatch",
"arguments": {
"requests": [
{"command": "equity.price.quote", "params": {"symbol": "AAPL"}, "id": "a"},
{"command": "equity.price.quote", "params": {"symbol": "MSFT"}, "id": "b"}
]
}
}

Each entry needs command (dotted path); params and id are optional. The id is opaque correlation echoed back on the matching response. Failures surface as response objects with ok=False and a structured error block — no exception bubbles up, errors are per-request.

openbb_list_commands

List every command with a one-line description. Takes only the optional server_url. The response's result is a list of {"name", "description"} entries. Equivalent to openbb --list-commands on the CLI.

openbb_describe_command

Return one command's parameters and output schema.

json
{
"name": "openbb_describe_command",
"arguments": {"command": "equity.price.historical", "provider": "yfinance"}
}

The response's result has the command name, its parameters (each with name, in, and type, plus required, default, choices, and help when set), and its output_schema. For a command with several providers, pass provider to get that provider's parameters and output_schema; without it, result.providers maps every provider to its own parameters and output_schema. Equivalent to openbb --describe equity.price.historical (equity.price.historical:yfinance for one provider) on the CLI.

Local vs remote dispatch
ModeTriggerBehavior
LocalNo server_url, no OPENBB_SERVER_URLLocalDispatcher resolves commands against the in-process obb namespace. Pays the heavy import openbb once at startup. Single-tenant.
Remoteserver_url arg or OPENBB_SERVER_URL envHttpDispatcher proxies commands to a long-running openbb-platform-api server. Multi-tenant; the heavy import lives on the server.

Mode is per-call — different requests in the same session can target different servers. Dispatchers are cached for the server's lifetime, so the import openbb cost (local) and the remote server's OpenAPI download are paid once per target.


Calling Data Tools

Input Parameters

Every data tool has a JSON Schema describing its input. A typical tool schema:

json
{
"type": "object",
"properties": {
"symbol": {
"type": "string",
"description": "Symbol to get data for."
},
"provider": {
"type": "string",
"enum": ["fmp", "polygon", "yfinance"],
"description": "The provider to use for the query."
},
"start_date": {
"anyOf": [{"type": "string", "format": "date"}, {"type": "null"}],
"description": "Start date of the data."
},
"end_date": {
"anyOf": [{"type": "string", "format": "date"}, {"type": "null"}],
"description": "End date of the data."
},
"interval": {
"type": "string",
"default": "1d",
"description": "Time interval of the data."
}
},
"required": ["symbol"]
}

Key rules:

  • `provider` — present only on endpoints that use the provider interface.

When listed, its enum shows available provider sources. If the endpoint has only one provider, you can omit it and the sole provider is used automatically. When multiple providers are available, select one from the enum. Different providers may return different fields or support different parameters. Endpoints that do not use the provider interface (basic GET/POST routes) have no provider parameter at all.

  • `symbol` formatting — symbols are case-insensitive. Multiple symbols can

be comma-separated: "AAPL,MSFT,GOOG".

  • Dates — always formatted as YYYY-MM-DD strings.
  • Optional parameters — have anyOf with a null type or a default

value. Omit them to use defaults.

  • Provider-specific parameters — some parameters are only relevant for

certain providers. The schema unions all of them; irrelevant ones are silently ignored.

  • Valid values — never guess a value. A parameter with a fixed set of

values has an enum. When the values differ by provider, or several can be comma-separated, the description lists them (Valid values by provider: ..., Valid values for provider oecd (comma-separate several): ...). When another tool lists them, the description names it and its arguments (`Get the valid values from the derivatives_options_strikes tool with symbol=<the symbol you pass here>.`) — call that tool first.

Example Tool Call
json
{
"name": "equity_price_historical",
"arguments": {
"symbol": "AAPL",
"provider": "fmp",
"start_date": "2025-01-01",
"end_date": "2025-02-01",
"interval": "1d"
}
}

Understanding the Response

Every OpenBB tool returns an OBBject — a standardized response envelope:

json
{
"id": "06520558-d54a-7e53-8000-7aafc8a42694",
"results": [...],
"provider": "fmp",
"warnings": null,
"chart": null,
"extra": {
"metadata": {
"arguments": {...},
"duration": 565256375,
"route": "/equity/price/historical",
"timestamp": "2025-01-15 11:28:57.149548"
}
}
}
Response Fields
FieldTypeDescription
idstringUUID identifying this request
results`list[dict] \dict \string \null`The actual data. Usually a list of records
provider`string \null`Which provider fulfilled the request
warnings`list[object] \null`Non-fatal warnings from the provider or platform
chart`object \null`Chart artifact if chart=true was passed
extradictExecution metadata and results metadata
The results Field

This is the primary data payload. Its structure depends on the endpoint:

Tabular data — most common, a list of dictionaries (one per row):

json
"results": [
{"date": "2025-01-02", "open": 150.0, "high": 155.0, "low": 149.0, "close": 153.5, "volume": 1000000},
{"date": "2025-01-03", "open": 153.0, "high": 157.0, "low": 152.0, "close": 156.2, "volume": 1200000}
]

Single record — some endpoints return a single dict:

json
"results": {"symbol": "AAPL", "price": 185.50, "change": 2.30, "volume": 45000000}

Empty results — when no data is available:

json
"results": null

or

json
"results": []

Field names vary by provider — different providers may return different columns for the same endpoint. Always check the keys in the returned records.

The warnings Field

Warnings are non-fatal issues that occurred during execution:

json
"warnings": [
{
"category": "OpenBBWarning",
"message": "Parameter 'source' is not supported by fmp. Available for: intrinio."
}
]

Common warning scenarios:

  • Unknown parameters silently ignored by the provider
  • Partial data returned (fewer rows than requested)
  • Provider-specific data quality notes

When warnings is null, no warnings were generated.

The extra Field

Contains execution metadata and optional results metadata:

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
70,028
Repository forks
7,083
7-day trend score
56

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 4 Jul 2026, 4 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/openbb-finance/openbb/work-with-server/badge)](https://verified-skill.com/skills/openbb-finance/openbb/work-with-server)

Something wrong with this skill or its page? Tell us.