Meta Agent Tools
PT

Back to the catalog

app.3dstreet/3dstreet

Drive an open 3DStreet scene tab from Claude Desktop or Claude Code via MCP tool calls.

Open source Open in the app JSON README (API)

About

Drive an open 3DStreet scene tab from Claude Desktop or Claude Code via MCP tool calls.

Details

Kind
MCP servers
Topic
No topic detected
Publisher
app.3dstreet
Origin
official
Category
ferramentas
Transport
local
Version
0.2.2
Last push
2026-09-03T18:20:26Z
Repository state
ativo
Language
JavaScript
License
AGPL-3.0
Added
2026-08-29 03:00:43
Updated
2026-08-29 03:00:43
Origin id
app.3dstreet/3dstreet

README

# 3dstreet-mcp

A [Model Context Protocol][mcp] relay that lets [Claude Desktop][cd] or
[Claude Code][cc] drive a [3DStreet][3ds] scene running in your browser.

> **Is this the right tool?** This relay is the **fallback** for MCP clients
> that cannot use WebMCP. If your agent runs *inside* a browser (ChatGPT's
> desktop browser, Gemini in Chrome, Chrome 149+ with the WebMCP origin
> trial or `chrome://flags/#enable-webmcp-testing`), you do not need this
> package: open <https://3dstreet.app> and the page registers the same
> tools with the browser via `document.modelContext` — nothing to install,
> no pairing. See the [3DStreet WebMCP docs][webmcp]. Use this relay only
> for clients with no browser of their own or no WebMCP support (Claude
> Desktop, Claude Code, Cursor, headless scripts). It will be retired once
> those clients read WebMCP natively.

Listed on the [MCP Registry][registry] as `app.3dstreet/3dstreet`.

Status: **alpha** — protocol may change. Tracks
[3DStreet#1582][issue] (design) and
[3DStreet#1600][pr] (browser side). Scene creation works in any
3dstreet.app tab; saving and geospatial features require a free
3DStreet account.

## How it works

```
Claude Desktop  ── stdio MCP ──▶  3dstreet-mcp  ── ws://127.0.0.1:51735 ──▶  3DStreet tab
or Claude Code                    (this package)                              (your browser)
```

The relay speaks MCP over stdio and bridges every `tools/list` and
`tools/call` to a 3DStreet tab over a localhost WebSocket. The tab does
the actual work — it's already signed in, has the catalog loaded, owns
the cloud-save flow. The relay is a dumb pipe.

No auth tokens cross the WebSocket. The relay's port binds to `127.0.0.1`
only and rejects WebSocket upgrades from origins outside the 3DStreet
allowlist (`https://3dstreet.app`, `https://dev-3dstreet.web.app`,
`http://localhost:3333`, `http://127.0.0.1:3333`).

## Setup

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "3dstreet": {
      "command": "npx",
      "args": ["-y", "3dstreet-mcp"]
    }
  }
}
```

Restart Claude Desktop.

### Claude Code

```bash
claude mcp add 3dstreet -- npx -y 3dstreet-mcp
```

### Pair the browser tab

On startup the relay prints an auto-pair URL to its log, like:

```
open this URL to pair a 3DStreet tab: https://3dstreet.app/#mcp
```

Open that URL in a signed-in browser and the editor will detect the
`#mcp` fragment, open the **AI Assistant** pane, and pair with the
relay automatically — no console commands needed. (If you ran the
relay on a non-default port the URL will look like
`https://3dstreet.app/#mcp=PORT`.)

If you'd rather pair manually: open <https://3dstreet.app>, click
**AI Assistant** in the right panel, type `/mcp`, and click
**Reconnect**.

You can now ask Claude things like:

- "What's in my current scene?"
- "Add a bike lane on the left side of the street."
- "Change the environment preset to night."

Toggle **Read-only** in the status bar to block scene mutations
(useful when you just want Claude to explain a scene).

## CLI

```
3dstreet-mcp [options]

Options:
  -p, --port <number>    WebSocket port (default 51735)
  -o, --origin <url>     Origin used in the printed auto-pair URL and
                         the MCP `instructions` hint (default
                         https://3dstreet.app — set to
                         http://localhost:3333 when running 3DStreet
                         from a local dev server)
  -h, --help             Show this help
  -v, --version          Print version and exit
```

If you need a different port (e.g. running two Claude clients against
two different tabs), pass `--port` and open the auto-pair URL the
relay prints — `https://3dstreet.app/#mcp=PORT` — which both selects
the port and triggers auto-pair.

For local 3DStreet development, point `--origin` at your dev server so
the printed URL and the LLM's `instructions` hint both resolve to the
right tab:

```bash
node src/cli.js --origin http://localhost:3333
# → open this URL to pair a 3DStreet tab: http://localhost:3333/#mcp
```

## Telling the LLM how to pair

The relay returns an `instructions` string on every `initialize` (an
optional MCP field clients may fold into the LLM's system prompt). It
explains that scene tools are forwarded to a paired tab, names the
auto-pair URL, and tells the model to surface that URL to the user
when no tab is connected — so the LLM proactively guides users
through pairing instead of waiting for an opaque tool-call timeout.

When no tab has *ever* paired this relay session, `tools/call` also
fast-fails with the auto-pair URL in the error message, rather than
queuing for 30 seconds. Once a tab has paired, brief disconnects
revert to the queued retry behaviour so reconnecting peers can drain
in-flight calls.

## Tools exposed

The tool list is fetched from the connected browser tab on pair, so it
always matches whatever the editor's command registry exposes. As of
[#1600][pr] that includes:

- **Reads:** `getScene`, `getEntity`, `getSelectedEntity`,
  `getManagedStreet`, `listMixins`, `getSessionInfo`
- **Selection / camera:** `selectEntity`, `focusCamera`
- **Mutations:** `entityCreate`, `entityUpdate`, `entityRemove`,
  `entityClone`, `entityReparent`, `componentAdd`, `componentRemove`,
  `segmentAdd`, `segmentUpdate`, `segmentRemove`, `replaceManagedStreet`,
  …and the rest of the registry
- **History:** `undo`, `redo`

Run `tools/list` from your MCP client to see the current set.

## Wire protocol (for contributors)

Stdio side: line-delimited JSON-RPC 2.0, MCP `2024-11-05`.

WebSocket side: same JSON-RPC envelope, with the relay handling
`initialize` / `ping` / notifications locally and forwarding only
`tools/list` and `tools/call` to the peer. The peer assigns its own ids
on incoming frames; replies match by id.

The single-peer policy: first browser tab to connect holds the slot.
Second connection gets WebSocket close code `4001` with reason
`paired-elsewhere`.

## Development

```bash
git clone https://github.com/3DStreet/3dstreet-mcp.git
cd 3dstreet-mcp
npm install
npm test
```

Smoke-test against a real 3DStreet build:

```bash
# Terminal 1 — the relay, REPL-free, just stdio
node src/cli.js

# Terminal 2 — exercise it with the MCP inspector
npx @modelcontextprotocol/inspector node src/cli.js
```

## License

AGPL-3.0-or-later, matching 3DStreet itself.

[mcp]: https://modelcontextprotocol.io
[webmcp]: https://github.com/3DStreet/3dstreet/blob/main/docs/webmcp.md
[cd]: https://claude.ai/download
[cc]: https://docs.claude.com/en/docs/claude-code
[3ds]: https://3dstreet.app
[issue]: https://github.com/3DStreet/3dstreet/issues/1582
[pr]: https://github.com/3DStreet/3dstreet/pull/1600
[registry]: https://registry.modelcontextprotocol.io/v0.1/servers?search=app.3dstreet/3dstreet

More