MCP Server

Connect Claude to B3OS and build, run, and debug blockchain workflows in plain English.

Connect Claude to B3OS and build, run, and debug blockchain workflows in plain English — no UI, no code, no context-switching.

Works with Claude Code, Claude Desktop, and agent teammates.

npm package

Install from npm.

MCP Protocol

Learn about the Model Context Protocol.

Manage API keys

Create or revoke API keys.

Quick Start

Install

bash
npm install -g @b3dotfun/b3os-mcp

Run setup

bash
b3os-mcp-setup

The wizard opens your browser, signs you in to B3OS, creates a dedicated API key scoped to this machine, and stores it securely in your OS keychain. Takes about 20 seconds.

Restart Claude

Restart your Claude Code session or Claude Desktop app, and you are done.

You only run the setup once. Re-running issues a new key under the same service account. To revoke a key, visit the API keys page in your org settings.

What You Can Do

Build workflows in one sentence

text
"Monitor ETH price every 5 minutes and alert me on Slack if it drops below $2000""Every Monday at 9am, swap 100 USDC to ETH on Base and email me a confirmation""When my wallet receives an ERC-20 token, log it to a Google Sheet and send a Telegram alert"

Claude searches the action catalog, picks the right triggers and connectors, wires them together, and asks you to review before publishing.

Query the chain

text
"What's the current price of ETH and BTC?""What tokens does vitalik.eth hold on Base?""Why did tx 0xabc... fail?""Show me the top Polymarket markets right now"

No workflow needed — answers come back inline using read-only action queries.

Debug with full execution context

text
"Why did my last workflow run fail?""Explain what this node did and how to fix it"

Claude pulls the execution trace, identifies which node failed, surfaces the error, and offers a fix you can apply with one more message.

Operate live workflows

text
"Pause my ETH alert workflow""Change the Slack channel in my swap notifier""Re-run last night's failed price snapshot"

Claude can list, get, update, publish, pause, resume, run, and trace any workflow you own.

Available Tools

The MCP server exposes 48 tools across seven areas.

Area	Tools	What they do
Action catalog	`b3os_search_actions`, `b3os_list_actions`, `b3os_get_action`, `b3os_list_logic_actions`, `b3os_list_triggers`, `b3os_get_trigger`	Search and inspect action schemas, trigger schemas, and connector requirements
Workflows	`b3os_create_workflow`, `b3os_build_workflow`, `b3os_get_workflow`, `b3os_update_workflow`, `b3os_validate_workflow`, `b3os_publish_workflow`, `b3os_pause_workflow`, `b3os_resume_workflow`, `b3os_rollback_workflow`, `b3os_delete_workflow`, `b3os_list_workflows`, `b3os_list_workflow_versions`, `b3os_get_workflow_schedule`	Full lifecycle management of workflow drafts and live versions
Runs	`b3os_run_workflow`, `b3os_run_ephemeral`, `b3os_run_action`, `b3os_get_run`, `b3os_list_runs`, `b3os_retry_run`, `b3os_cancel_run`, `b3os_debug_run`, `b3os_test_trigger`	Trigger, trace, retry, and debug workflow executions
Data queries	`b3os_query_action`, `b3os_query_database`, `b3os_get_table_schema`, `b3os_list_tables`	Read-only action proxy and database queries (no CU cost)
Lookups	`b3os_price_lookup`, `b3os_token_lookup`, `b3os_balance_lookup`, `b3os_defi_lookup`, `b3os_polymarket_lookup`, `b3os_debug_transaction`	Inline chain data, prices, balances, DeFi positions, and tx debugging
Organization	`b3os_whoami`, `b3os_list_wallets`, `b3os_list_connectors`, `b3os_list_connector_types`, `b3os_list_slack_channels`, `b3os_list_telegram_chats`, `b3os_get_cu_balance`, `b3os_logout`	Organization context, wallets, connectors, and billing
Templates	`b3os_list_templates`, `b3os_get_template`	Browse and inspect reusable workflow templates

Read operations (lookups, listings, schemas, traces) run freely. Write operations — creating workflows, publishing, executing on-chain actions, triggering runs — always require your explicit approval per call.

Configuration

Environment variables

Variable	Required	Description
`B3OS_API_KEY`	No	API key — on macOS/Windows the key is read from the OS keychain automatically. Set this only on Linux, CI, or to override the keychain.
`B3OS_SERVER_URL`	No	Override the API endpoint (defaults to B3OS production).

CI and headless environments

For machines without a browser, create an API key from the B3OS dashboard and set it directly:

bash
export B3OS_API_KEY=b3sk_...

Manual config

The setup wizard handles everything, but if you need to edit your Claude config by hand:

json
{  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp",      "env": {        "B3OS_SERVER_URL": "https://api.b3os.org"      }    }  }}

json
{  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp",      "env": {        "B3OS_API_KEY": "b3sk_your_key_here",        "B3OS_SERVER_URL": "https://api.b3os.org"      }    }  }}

If b3os-mcp is not resolved — common with Claude Desktop since it does not inherit your shell PATH — replace "command": "b3os-mcp" with the absolute node path and the absolute path to dist/index.js. The interactive setup handles this automatically.

Security

Concern	How it is handled
Key storage	macOS Keychain (encrypted at rest), Windows DPAPI (machine-scoped encryption), Linux `~/.claude/mcp.json` with `0600` permissions
Key scope	Each install creates a dedicated API key named `b3os-mcp@<hostname>`
Wallet keys	Signing happens server-side; private keys are never exposed to Claude or the MCP server
Session tokens	Discarded immediately after login — only the long-lived API key is persisted
Write safety	All write operations require explicit user approval per call
Revocation	Revoke anytime at b3os.org/organizations/settings?tab=api-keys

Setup by Platform

The B3OS MCP server works with any client implementing the MCP stdio transport. Below are config snippets for popular editors and AI tools.

json
// ~/.claude/mcp.json (auto-configured by b3os-mcp-setup){  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp"    }  }}

json
// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)// %APPDATA%\Claude\claude_desktop_config.json (Windows){  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp"    }  }}

json
// .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global){  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp"    }  }}

json
// ~/.codeium/windsurf/mcp_config.json{  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp"    }  }}

json
// Settings > Cline > MCP Servers, or .vscode/cline_mcp_settings.json{  "mcpServers": {    "b3os-mcp": {      "type": "stdio",      "command": "b3os-mcp"    }  }}

After running b3os-mcp-setup once (which stores the API key in your OS keychain), any MCP client on the same machine can connect without additional auth config.

End-to-End Example

This walkthrough shows how an MCP conversation builds a complete workflow from scratch.

Describe your goal

text
You: "Build a workflow that checks ETH price every hour and sends me aTelegram message if it drops below $2000"

Claude searches the catalog

Claude calls b3os_search_actions to find the right price-check and messaging actions, then b3os_list_triggers to pick the schedule trigger. It also calls b3os_list_connectors and b3os_list_telegram_chats to discover your available Telegram bot.

Claude builds the workflow

Claude calls b3os_build_workflow with the full definition — a cronjob trigger firing every hour, a coingecko-get-price action, an if condition checking {{coingecko.result.price}} < 2000, and a telegram-send-message action on the true branch.

You review and approve

Claude presents the workflow graph and asks for confirmation. You approve the write operation.

Test before publishing

Claude calls b3os_run_ephemeral to dry-run the workflow with a simulated trigger payload. You see each node result inline.

Publish

Claude calls b3os_publish_workflow. The schedule is now live and the first run fires within the hour.

Debug later

text
You: "My ETH alert workflow failed last night — what happened?"

Claude calls b3os_list_runs to find the failed execution, then b3os_debug_run to surface the failing node and error. It might suggest a fix — like updating the Telegram chat ID — and apply it with b3os_update_workflow.