mcp-spatial-perception
Give your AI agent eyes on the physical world.
An MCP server that exposes real-time spatial perception queries from DePIN edge-vision nodes to any LLM that speaks the Model Context Protocol — Claude Desktop, Cursor, Claude Code, or a custom agent framework.
The problem
LLM agents can read files, browse the web, and call APIs — but they're blind to the physical world. They can't answer questions like:
- "Is there foot traffic at location X right now?"
- "What is the live visual state of camera node #402?"
- "Is the loading dock clear before I dispatch the truck?"
There's no standard way for an agent to ask those questions.
The solution
mcp-spatial-perception is a small, dependency-free MCP server that sits between your agent and a DePIN network of edge-vision nodes. The agent calls a tool, the server queries the network, and structured JSON describing the scene comes back — detections, bounding boxes, confidence scores, environmental state, geolocation.
┌─────────────┐ MCP / JSON-RPC ┌───────────────────────┐ DePIN query ┌──────────────┐
│ LLM agent │ ─────────────────► │ mcp-spatial-perception│ ──────────────► │ edge nodes │
│ (Claude, │ ◄───────────────── │ (this repo) │ ◄────────────── │ (cameras, │
│ Cursor…) │ structured JSON └───────────────────────┘ telemetry │ sensors) │
└─────────────┘ └──────────────┘
Install
pip install mcp-spatial-perception
Requires Python 3.10+. No runtime dependencies — pure standard library.
Use with Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"spatial-perception": {
"command": "mcp-spatial-perception"
}
}
}
Restart Claude Desktop. The query_spatial_feed tool will appear in the tool picker.
Use with Cursor / Claude Code / any MCP client
The server speaks JSON-RPC 2.0 over stdio. Any MCP-compatible client can launch it via the mcp-spatial-perception console script:
mcp-spatial-perception
Or directly, if you have the source checked out:
python mcp_spatial.py
Use programmatically
from mcp_spatial import handle_mcp_request
response = handle_mcp_request({
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "query_spatial_feed",
"arguments": {"node_id": "node_402"}
}
})
print(response["result"]["content"][0]["text"])
The query_spatial_feed tool
Input
| Field | Type | Required | Description |
|---|---|---|---|
node_id |
string |
yes | The DePIN node ID to query. |
Output — structured JSON describing the node's current visual state:
{
"node_id": "node_402",
"timestamp": 1770000000,
"location": { "lat": 9.0765, "lon": 7.3986 },
"detections": [
{
"object": "delivery_truck",
"confidence": 0.94,
"bounding_box": [120, 80, 450, 300]
},
{
"object": "person",
"confidence": 0.88,
"bounding_box": [50, 60, 110, 200]
}
],
"environmental": { "light_level": "daylight", "obscured": false }
}
| Field | Meaning |
|---|---|
node_id |
Echo of the queried node. |
timestamp |
Unix seconds when the frame was captured. |
location |
Latitude / longitude of the node. |
detections |
Objects found in the frame, with bounding boxes. |
environmental |
Lighting, occlusion, and other scene conditions. |
FAQ
Why an MCP server and not just a REST API? Because MCP is what Claude Desktop, Cursor, and Claude Code speak natively. A REST API would require each client to write a custom integration. An MCP server is a drop-in tool for every MCP-aware agent.
Why is the feed mocked right now?
To keep the protocol surface testable and stable while the DePIN adapter is built. The mock_node_feed function is a single, well-isolated seam — swapping it for a real network client doesn't touch the MCP logic.
Does this run the vision model? No. Edge nodes do the frame extraction and inference on-device; this server relays the structured result. That's the point of DePIN — the compute is at the edge, not in your agent's process.
Status
⚠️ Alpha. The MCP protocol surface is stable, but the node feed is currently mocked. A real DePIN adapter is on the roadmap.
Roadmap
- Spec-compliant MCP server (
initialize,tools/list,tools/call) - Published to PyPI with Trusted Publishing
- CI: lint (ruff), type-check (mypy strict), test (pytest) on Python 3.10–3.12
- Replace mock feed with a real DePIN adapter
- Add
query_by_location(lat, lon)tool - Add
subscribe_to_node(node_id)push notifications - Frame snapshot retrieval
- Auth / signed node requests
Development
git clone https://github.com/jamie643/mcp-spatial-perception.git
cd mcp-spatial-perception
pip install -e ".[dev]"
ruff check . # lint
ruff format --check . # format check
mypy mcp_spatial.py # type-check (strict)
pytest # tests + coverage
Contributing
Issues and pull requests are welcome. For substantial changes, please open an issue first to discuss what you'd like to change.
License
MIT © 2026 Jamie643
Metadata
Release files for mcp-spatial-perception 0.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_spatial_perception-0.1.4.tar.gz | 7.1 kB | With provenance | Details for mcp_spatial_perception-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_spatial_perception-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for mcp_spatial_perception-0.1.4-py3-none-any.whl |
Total release size: 14.6 kB
Release files / mcp_spatial_perception-0.1.4.tar.gz
| Download URL | mcp_spatial_perception-0.1.4.tar.gz |
|---|---|
| Size | 7.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ac4a312d4bd93831c3b9fe027c3c56a308d9c3d067452775f2b2c88e8ac53f1
|
|
BLAKE2b-256 checksum How to use checksums |
0b4eec0959759a57c6a4285f3ba0e2aae664fa7208b1e412096fac64568a47a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logRelease files / mcp_spatial_perception-0.1.4-py3-none-any.whl
| Download URL | mcp_spatial_perception-0.1.4-py3-none-any.whl |
|---|---|
| Size | 7.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
350c6d7f6602057fb9eb31d5a846d0231de98c497166ddd38e46ffc6768b6c66
|
|
BLAKE2b-256 checksum How to use checksums |
893e2b214e05ba09986d7e27b8cb6b73034640a1a5e622a38090cdfa89603e27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logSecurity for mcp-spatial-perception 0.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_spatial_perception-0.1.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.