Metadata-Version: 2.4
Name: streamlit-mcp
Version: 0.1.0
Summary: Serve an existing Streamlit app as an MCP server — agents drive it natively, no browser.
Project-URL: Homepage, https://github.com/dkedar7/streamlit-mcp
Project-URL: Source, https://github.com/dkedar7/streamlit-mcp
Project-URL: Bug Tracker, https://github.com/dkedar7/streamlit-mcp/issues
Project-URL: Changelog, https://github.com/dkedar7/streamlit-mcp/blob/main/CHANGELOG.md
Author: Kedar Dabhadkar
License: MIT License
        
        Copyright (c) 2026 Kedar Dabhadkar
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,automation,llm,mcp,model-context-protocol,streamlit
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp<4,>=3
Requires-Dist: streamlit>=1.58
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# streamlit-mcp

**Serve any Streamlit app as an MCP server.** Agents introspect your app's widgets,
set values, click buttons, and read the rendered output and `session_state` — natively,
over MCP, with **no browser automation**.

```bash
uv tool install .        # or: pip install .

# serve an app over MCP (stdio for local clients, or HTTP/SSE for networked agents)
streamlit-mcp serve app.py
streamlit-mcp serve app.py --transport http --host 127.0.0.1 --port 8000

# drive it yourself from the terminal (same engine the agent uses)
streamlit-mcp inspect app.py
streamlit-mcp call app.py --set "Name=agent" --click "Save" --read
```

Streamlit has no callback graph — it reruns the whole script per interaction — so
streamlit-mcp drives the app headlessly through Streamlit's own test runtime
(`streamlit.testing.v1.AppTest`) and returns the **semantic element tree**, not pixels.
Gradio and Dash already shipped native app-as-MCP; this fills the Streamlit gap.

## Tools exposed to agents

| Tool | What it does |
|---|---|
| `list_widgets` / `get_layout` | introspect widgets (kind, label, value, constraints) |
| `set_widget(identifier, value)` | set a widget and rerun |
| `click(identifier)` | click a button and rerun |
| `read_output()` | the rendered element tree, agent-readable |
| `get_state()` | the app's `session_state` |

Supported widgets (v1): text_input, number_input, text_area, slider, selectbox,
multiselect, checkbox, radio, button, date_input. Unsupported elements (file_uploader,
custom components, `st.chat`, fragments) are reported explicitly, never silently dropped.

## Human ↔ agent parity

Everything an agent can do over MCP, a human can do via the CLI — both call the same
engine. The read-only mode and widget allow-list guardrails apply identically to both
surfaces.

## Security / trust model

- **`app_path` is executed as trusted code** in the server process (that's how AppTest
  runs it). Only serve apps you trust.
- **`get_state` / `read_output` expose the app's `session_state`** to the caller — do not
  put secrets there.
- **HTTP/SSE is loopback-only in v1.** A bearer-token primitive exists, but it is **not yet
  enforced** on the transport, so `serve` refuses to bind HTTP/SSE to a non-loopback host.
  Use stdio for local clients, or HTTP/SSE on `127.0.0.1`. Enforced networked auth is the
  top follow-up (see `CHANGELOG.md`).

## License

MIT
