This release is a pre-release and may not be stable for production use.
Smooth Python SDK
The Smooth Python SDK provides a convenient way to interact with the Smooth API for programmatic browser automation and task execution.
Features
- Synchronous and Asynchronous Clients: Choose between
SmoothClientfor traditional sequential programming andSmoothAsyncClientfor high-performance asynchronous applications. - Task Management: Easily run tasks and retrieve results upon completion.
- Interactive Browser Sessions: Get access to, interact with, and delete stateful browser sessions to manage your login credentials.
- Advanced Task Configuration: Customize task execution with options for device type, session recording, stealth mode, and proxy settings.
- 🆕 MCP Server: Use the included Model Context Protocol server to integrate browser automation with AI assistants like Claude Desktop.
Installation
You can install the Smooth Python SDK using pip:
pip install smooth-py
For MCP server functionality, also install FastMCP:
pip install fastmcp
Quick Start Options
Option 1: Direct SDK Usage
Use the SDK directly in your Python applications:
Option 2: MCP Server (AI Assistant Integration)
Use the included MCP server to integrate browser automation with AI assistants:
Installation
# Install with MCP support
pip install smooth-py[mcp]
Basic Usage
from smooth.mcp import SmoothMCP
# Create and run the MCP server
mcp = SmoothMCP(api_key="your-api-key")
mcp.run() # STDIO transport for Claude Desktop
# Or with HTTP transport for web deployment
mcp.run(transport="http", host="0.0.0.0", port=8000)
Standalone Script (Backward Compatible)
# Set your API key
export CIRCLEMIND_API_KEY="your-api-key-here"
# Run the MCP server
python mcp_server.py
Then configure your AI assistant (like Claude Desktop) to use the MCP server. See MCP_README.md for detailed setup instructions.
Authentication
The SDK requires an API key for authentication. You can provide the API key in two ways:
-
Directly in the client constructor:
from smooth import SmoothClient client = SmoothClient(api_key="YOUR_API_KEY")
-
As an environment variable:
Set the
CIRCLEMIND_API_KEYenvironment variable, and the client will automatically use it.export CIRCLEMIND_API_KEY="YOUR_API_KEY"
from smooth import SmoothClient # The client will pick up the API key from the environment variable client = SmoothClient()
Usage
Synchronous Client
The SmoothClient is ideal for scripts and applications that don't require asynchronous operations.
Running a Task and Waiting for the Result
The run method returns a TaskHandle. You can use the result() method on this handle to wait for the task to complete and get its final state.
from smooth import SmoothClient
from smooth.models import ApiError, TimeoutError
with SmoothClient() as client:
try:
# The run method returns a handle to the task immediately
task_handle = client.run(
task="Go to https://www.google.com and search for 'Smooth SDK'",
device="desktop",
enable_recording=True
)
print(f"Task submitted with ID: {task_handle.id}")
print(f"Live view available at: {task_handle.live_url}")
# The result() method waits for the task to complete
completed_task = task_handle.result()
if completed_task.status == "done":
print("Task Result:", completed_task.output)
print(f"View recording at: {completed_task.recording_url}")
else:
print("Task Failed:", completed_task.output)
except TimeoutError:
print("The task timed out.")
except ApiError as e:
print(f"An API error occurred: {e}")
Managing Browser Sessions
You can create, list, and delete browser sessions to maintain state (like logins) between tasks.
from smooth import SmoothClient
with SmoothClient() as client:
# Create a new browser session
browser_session = client.open_session()
print("Live URL:", browser_session.live_url)
print("Session ID:", browser_session.session_id)
# List all browser sessions
sessions = client.list_sessions()
print("All Session IDs:", sessions.session_ids)
# Delete the browser session
client.delete_session(session_id=session_id)
print(f"Session '{session_id}' deleted.")
Asynchronous Client
The SmoothAsyncClient is designed for use in asynchronous applications, such as those built with asyncio, to handle multiple operations concurrently without blocking.
Running a Task and Waiting for the Result
The run method returns an AsyncTaskHandle. Await the result() method on the handle to get the final task status.
import asyncio
from smooth import SmoothAsyncClient
from smooth.models import ApiError, TimeoutError
async def main():
async with SmoothAsyncClient() as client:
try:
# The run method returns a handle to the task immediately
task_handle = await client.run(
task="Go to Github and search for \"smooth-sdk\""
)
print(f"Task submitted with ID: {task_handle.id}")
print(f"Live view available at: {task_handle.live_url}")
# The result() method waits for the task to complete
completed_task = await task_handle.result()
if completed_task.status == "done":
print("Task Result:", completed_task.output)
else:
print("Task Failed:", completed_task.output)
except TimeoutError:
print("The task timed out.")
except ApiError as e:
print(f"An API error occurred: {e}")
if __name__ == "__main__":
asyncio.run(main())
MCP Server (AI Assistant Integration)
The Smooth SDK includes a Model Context Protocol (MCP) server that allows AI assistants like Claude Desktop or Cursor to perform browser automation tasks through natural language commands.
Installation
pip install smooth-py[mcp]
Basic Usage
from smooth.mcp import SmoothMCP
# Create and run the MCP server
mcp = SmoothMCP(api_key="your-api-key")
mcp.run()
Example MCP Usage
Once configured, you can ask your MCP client to perform browser automation:
- "Please go to news.ycombinator.com and get the top 5 story titles"
- "Create a browser session, log into Gmail, and check for unread emails"
- "Go to Amazon and search for wireless headphones under $100"
- "Fill out the contact form at example.com with test data"
1 maintainer
Metadata
1 maintainer
Release files for smooth-py 0.2.3.dev20250922
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| smooth_py-0.2.3.dev20250922.tar.gz | 14.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| smooth_py-0.2.3.dev20250922-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 29.0 kB
Release files / smooth_py-0.2.3.dev20250922.tar.gz
| Download URL | smooth_py-0.2.3.dev20250922.tar.gz |
|---|---|
| Size | 14.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e31bf2bbf8fdd0766ed71c032e930aa6116959bfb2f68789820f8ff4b86176a2
|
|
BLAKE2b-256 checksum How to use checksums |
a71b1a02e8d7f9fcbc63fd83ef6b267b6206213bfae4b73493e60b81c2064c18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Sep 22, 2025.
Transparency logRelease files / smooth_py-0.2.3.dev20250922-py3-none-any.whl
| Download URL | smooth_py-0.2.3.dev20250922-py3-none-any.whl |
|---|---|
| Size | 14.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d544a87006143b654dad8dd4ed276f5b3dadd7573c2aac62ab2f230ebeb4354
|
|
BLAKE2b-256 checksum How to use checksums |
4772c5f13b6b583060cdce939a19f9b36381a79b4ed2e80eaa5f0bbed26560a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
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 Sep 22, 2025.
Transparency log
