Merge pull request #25 from alexander-zuev/feat/small-improv

feat(sdk): enable python sdk usage locally

Author: alexander-zuev

README.md

@@ -26,6 +26,7 @@
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+" /></a>
   <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet" alt="uv package manager" /></a>
   <a href="https://pepy.tech/project/supabase-mcp-server"><img src="https://static.pepy.tech/badge/supabase-mcp-server" alt="PyPI Downloads" /></a>
+  <a href="https://smithery.ai/badge/@alexander-zuev/supabase-mcp-server"><img src="https://smithery.ai/badge/@alexander-zuev/supabase-mcp-server" alt="Smithery.ai Downloads" /></a>
   <a href="https://modelcontextprotocol.io/introduction"><img src="https://img.shields.io/badge/MCP-Server-orange" alt="MCP Server" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" /></a>
 </p>
@@ -117,6 +118,8 @@ After installing the package, you'll need to configure your database connection
  Server is pre-configured to connect to the local Supabase instance using default settings:
 - `Host`: 127.0.0.1:54322
 - `Password`: postgres
+- `API URL` : http://127.0.0.1:54321
+
 
 >💡 As long as you didn't modify the default settings and you want to connect to the local instance, you don't need to set environment variables.
 
@@ -129,6 +132,7 @@ For remote Supabase projects, you need to configure:
 - `SUPABASE_DB_PASSWORD` - Your database password
 - `SUPABASE_REGION` - (Optional) Defaults to `us-east-1`
 - `SUPABASE_ACCESS_TOKEN` - (Optional) For Management API access
+- `SUPABASE_SERVICE_ROLE_KEY` - (Optional) For Auth Admin SDK access
 
 You can get your SUPABASE_PROJECT_REF from your project's dashboard URL:
 - `https://supabase.com/dashboard/project/<supabase-project-ref>`
@@ -168,11 +172,11 @@ You can create project-specific MCP by:
 ```json
 {
 	"mcpServers": {
-	  "filesystem": {
-		"command": "supabase-mcp-server",
+	  "supabase": {
+		"command": "supabase-mcp-server"
 	  }
 	}
-  }
+}
 ```
 
 Alternatively, if you want to configure MCP servers globally (i.e. not for each project), you can use configure connection settings by updating an `.env` file in a global config folder by running the following commands:
@@ -203,6 +207,7 @@ SUPABASE_PROJECT_REF=your-project-ref
 SUPABASE_DB_PASSWORD=your-db-password
 SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1
 SUPABASE_ACCESS_TOKEN=your-access-token  # optional, for management API
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key # optional, for Auth Admin SDK
 ```
 
 Verify the file exists - you should see the values you have just set:
@@ -230,7 +235,8 @@ Windsurf supports de facto standard .json format for MCP Servers configuration.
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
-          "SUPABASE_ACCESS_TOKEN": "your-access-token"  // optional, for management API
+          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
+          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
         }
       }
     }
@@ -279,7 +285,8 @@ Go to Cascade -> Click on the hammer icon -> Configure -> Fill in the configurat
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
-          "SUPABASE_ACCESS_TOKEN": "your-access-token"  // optional, for management API
+          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
+          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
         }
       }
     }
@@ -386,6 +393,7 @@ Since v0.3.0 server supports sending arbitrary requests to Supabase Management A
     - Divides API methods into `safe`, `unsafe` and `blocked` categories based on the risk of the operation
     - Allows to switch between safe and unsafe modes dynamically
     - Blocked operations (delete project, delete database) are not allowed regardless of the mode
+  - **Note**: Management API tools only work with remote Supabase instances and are not compatible with local Supabase development setups.
 
 ### Auth Admin tools
 I was planning to add support for Python SDK methods to the MCP server. Upon consideration I decided to only add support for Auth admin methods as I often found myself manually creating test users which was prone to errors and time consuming. Now I can just ask Cursor to create a test user and it will be done seamlessly. Check out the full Auth Admin SDK method docs to know what it can do.

supabase_mcp/main.py

@@ -71,7 +71,7 @@ async def get_table_schema(schema_name: str, table: str):
 3. NEVER mix READ and WRITE operations in the same query
 4. NEVER use single DDL statements without transaction control
 5. Remember to enable unsafe mode first with live_dangerously('database', True)
-6. For auth operations (primarily creating, updating, deleting users, generating links, etc), prefer using the Auth Admin SDK methods 
+6. For auth operations (primarily creating, updating, deleting users, generating links, etc), prefer using the Auth Admin SDK methods
    instead of direct SQL manipulation to ensure correctness and prevent security issues
 
 TRANSACTION HANDLING:
@@ -229,12 +229,10 @@ async def get_auth_admin_methods_spec() -> dict:
 2. Create user:
    method: "create_user"
    params: {
-     "attributes": {
-       "email": "user@example.com",
-       "password": "secure-password",
-       "email_confirm": true,
-       "user_metadata": {"name": "John Doe"}
-     }
+     "email": "user@example.com",
+     "password": "secure-password",
+     "email_confirm": true,
+     "user_metadata": {"name": "John Doe"}
    }
 
 3. Generate link:

supabase_mcp/sdk_client/python_client.py

@@ -43,6 +43,9 @@ def __init__(self, project_ref: str, service_role_key: str):
 
     def get_supabase_url(self) -> str:
         """Returns the Supabase URL based on the project reference"""
+        if self.project_ref.startswith("127.0.0.1"):
+            # Return the default Supabase API URL
+            return "http://127.0.0.1:54321"
         return f"https://{self.project_ref}.supabase.co"
 
     @classmethod

tests/sdk_client/test_python_client.py

@@ -104,3 +104,19 @@ async def test_method_exception_handling(self, sdk_client, mock_supabase_client)
 
         assert error_message in str(excinfo.value)
         assert "Error calling get_user_by_id" in str(excinfo.value)
+
+    async def test_local_url_construction_with_port(self):
+        """Test URL construction for local instance with IP and port"""
+        # Test that the implementation correctly handles a project_ref with a port
+        client = SupabaseSDKClient("127.0.0.1:5432", "my-key")
+        url = client.get_supabase_url()
+        # The implementation should extract just the host and use port 54321
+        assert url == "http://127.0.0.1:54321"
+
+    async def test_local_url_construction_with_default_settings(self):
+        """Test URL construction for local instance with default settings"""
+        # Test with the default project_ref from settings (127.0.0.1:54322)
+        client = SupabaseSDKClient("127.0.0.1:54322", "my-key")
+        url = client.get_supabase_url()
+        # The implementation should extract just the host and use port 54321
+        assert url == "http://127.0.0.1:54321"