InstaWP · jack-arturo · Sep 30, 2025 · Sep 30, 2025
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@ build
 package-lock.json
 logs
 *.code-workspace
+.claude/settings.local.json
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -27,13 +27,34 @@ npm run clean
 ```
 
 ### Environment Setup
+
+#### Single Site Configuration
 Create a `.env` file in the project root with:
 ```env
 WORDPRESS_API_URL=https://your-wordpress-site.com
 WORDPRESS_USERNAME=wp_username
 WORDPRESS_PASSWORD=wp_app_password
 ```
 
+#### Multi-Site Configuration
+For managing multiple WordPress sites:
+```env
+# Site 1 (Production)
+WORDPRESS_1_URL=https://production-site.com
+WORDPRESS_1_USERNAME=admin
+WORDPRESS_1_PASSWORD=app_password_1
+WORDPRESS_1_ID=production
+WORDPRESS_1_DEFAULT=true
+WORDPRESS_1_ALIASES=prod,main
+
+# Site 2 (Staging)
+WORDPRESS_2_URL=https://staging-site.com
+WORDPRESS_2_USERNAME=admin
+WORDPRESS_2_PASSWORD=app_password_2
+WORDPRESS_2_ID=staging
+WORDPRESS_2_ALIASES=stage,dev
+```
+
 The app password can be generated from WordPress admin panel following the [Application Passwords guide](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide#Getting-Credentials).
 
 ## Architecture
@@ -46,17 +67,26 @@ The app password can be generated from WordPress admin panel following the [Appl
    - Uses StdioServerTransport for communication with Claude Desktop
    - Validates environment variables and establishes WordPress connection on startup
 
-2. **WordPress Client (`src/wordpress.ts`)**:
+2. **Site Manager (`src/config/site-manager.ts`)**:
+   - Manages multiple WordPress site configurations
+   - Lazy loads site configurations from environment variables
+   - Maintains separate authenticated Axios clients for each site
+   - Provides site detection from context (domain mentions, aliases, site IDs)
+   - Supports both numbered multi-site config and legacy single-site config
+
+3. **WordPress Client (`src/wordpress.ts`)**:
    - Manages authenticated Axios instance for WordPress REST API calls
+   - Integrates with SiteManager for multi-site support
    - Handles authentication using Basic Auth with application passwords
-   - Provides `makeWordPressRequest()` wrapper for all API calls
+   - Provides `makeWordPressRequest()` wrapper for all API calls with optional `siteId` parameter
    - Includes logging to `logs/wordpress-api.log` for debugging
    - Special handler `searchWordPressPluginRepository()` for WordPress.org plugin search
 
-3. **Tool System (`src/tools/`)**: 
+4. **Tool System (`src/tools/`)**: 
    - Each WordPress entity (posts, pages, media, etc.) has its own module
    - Each module exports tools array and handlers object
    - Tools use Zod schemas for input validation and type safety
+   - All tools support optional `site_id` parameter for multi-site support
    - All tools are aggregated in `src/tools/index.ts`
 
 ### Tool Pattern
@@ -115,6 +145,11 @@ Handles ALL taxonomies (categories, tags, custom taxonomies) with a single set o
 - `assign_terms_to_content` - Assign terms to any content type
 - `get_content_terms` - Get all terms for any content
 
+#### **Site Management Tools** (`site-management.ts`) - 3 tools
+- `list_sites` - List all configured WordPress sites
+- `get_site` - Get details about a specific site
+- `test_site` - Test connection to a WordPress site
+
 #### **Other Specialized Tools**
 - **Media** (`media.ts`): Media library management (~5 tools)
 - **Users** (`users.ts`): User management (~5 tools)
@@ -159,6 +194,20 @@ All taxonomy operations use a single `taxonomy` parameter:
 }
 ```
 
+#### Multi-Site Support
+All tools accept an optional `site_id` parameter to target specific sites:
+```json
+{
+  "content_type": "post",
+  "site_id": "production"  // Optional - targets specific site
+}
+```
+
+If `site_id` is not provided, the default site is used. Sites can be managed via:
+- `list_sites` - See all configured sites
+- `get_site` - Get details about a site
+- `test_site` - Test connection to a site
+
 ## TypeScript Configuration
 
 - Target: ES2022 with ESNext modules

diff --git a/README.md b/README.md
@@ -16,7 +16,16 @@ This is a Model Context Protocol (MCP) server for WordPress, allowing you to int
 
 ## Features
 
-This server currently provides tools to interact with core WordPress data:
+This server provides tools to interact with core WordPress data and supports **multi-site management** - manage multiple WordPress sites from a single MCP server instance.
+
+### **Multi-Site Management** (3 tools)
+Manage multiple WordPress sites from a single MCP server:
+
+*   `list_sites`: List all configured WordPress sites
+*   `get_site`: Get details about a specific site configuration
+*   `test_site`: Test connection to a specific WordPress site
+
+All content and taxonomy tools support an optional `site_id` parameter to target specific sites.
 
 ### **Unified Content Management** (8 tools)
 Handles ALL content types (posts, pages, custom post types) with a single set of intelligent tools:
@@ -103,22 +112,65 @@ All taxonomy operations use a single `taxonomy` parameter:
 }
 ```
 
-## Using with npx and .env file
+## Configuration
 
-You can run this MCP server directly using npx without installing it globally:
-
-```bash
-npx -y @instawp/mcp-wp
-```
+### Single Site Configuration
 
-Make sure you have a `.env` file in your current directory with the following variables:
+For managing a single WordPress site, use the following environment variables:
 
 ```env
 WORDPRESS_API_URL=https://your-wordpress-site.com
 WORDPRESS_USERNAME=wp_username
 WORDPRESS_PASSWORD=wp_app_password
 ```
 
+### Multi-Site Configuration
+
+To manage multiple WordPress sites from a single MCP server, use numbered environment variables:
+
+```env
+# Site 1 (Production)
+WORDPRESS_1_URL=https://production-site.com
+WORDPRESS_1_USERNAME=admin
+WORDPRESS_1_PASSWORD=app_password_1
+WORDPRESS_1_ID=production
+WORDPRESS_1_DEFAULT=true
+WORDPRESS_1_ALIASES=prod,main
+
+# Site 2 (Staging)
+WORDPRESS_2_URL=https://staging-site.com
+WORDPRESS_2_USERNAME=admin
+WORDPRESS_2_PASSWORD=app_password_2
+WORDPRESS_2_ID=staging
+WORDPRESS_2_ALIASES=stage,dev
+
+# Site 3 (Development)
+WORDPRESS_3_URL=https://dev-site.com
+WORDPRESS_3_USERNAME=admin
+WORDPRESS_3_PASSWORD=app_password_3
+WORDPRESS_3_ID=development
+```
+
+**Multi-Site Configuration Options:**
+- `WORDPRESS_N_URL`: WordPress site URL (required)
+- `WORDPRESS_N_USERNAME`: WordPress username (required)
+- `WORDPRESS_N_PASSWORD`: WordPress application password (required)
+- `WORDPRESS_N_ID`: Site identifier (optional, defaults to `siteN`)
+- `WORDPRESS_N_DEFAULT`: Set to `true` to make this the default site (optional, first site is default)
+- `WORDPRESS_N_ALIASES`: Comma-separated aliases for site detection (optional)
+
+The server supports up to 10 sites. When using multi-site configuration, all tools accept an optional `site_id` parameter to target specific sites.
+
+## Using with npx and .env file
+
+You can run this MCP server directly using npx without installing it globally:
+
+```bash
+npx -y @instawp/mcp-wp
+```
+
+Make sure you have a `.env` file in your current directory with the configuration variables shown above.
+
 ## Development
 
 ### Prerequisites
@@ -145,13 +197,28 @@ WORDPRESS_PASSWORD=wp_app_password
 
 3.  **Create a `.env` file:**
 
-    Create a `.env` file in the root of your project directory and add your WordPress API credentials:
-
+    Create a `.env` file in the root of your project directory and add your WordPress API credentials.
+
+    For a single site:
     ```env
     WORDPRESS_API_URL=https://your-wordpress-site.com
     WORDPRESS_USERNAME=wp_username
     WORDPRESS_PASSWORD=wp_app_password
     ```
+
+    For multiple sites:
+    ```env
+    WORDPRESS_1_URL=https://site1.com
+    WORDPRESS_1_USERNAME=admin
+    WORDPRESS_1_PASSWORD=app_password_1
+    WORDPRESS_1_ID=site1
+    WORDPRESS_1_DEFAULT=true
+
+    WORDPRESS_2_URL=https://site2.com
+    WORDPRESS_2_USERNAME=admin
+    WORDPRESS_2_PASSWORD=app_password_2
+    WORDPRESS_2_ID=site2
+    ```
 
     Replace the placeholders with your actual values.
 
@@ -202,10 +269,13 @@ src/
 ├── server.ts                    # MCP server entry point
 ├── wordpress.ts                 # WordPress REST API client
 ├── cli.ts                      # CLI interface
+├── config/
+│   └── site-manager.ts         # Multi-site management
 ├── types/
 │   └── wordpress-types.ts      # TypeScript definitions
 └── tools/
     ├── index.ts                # Tool aggregation
+    ├── site-management.ts      # Site management (3 tools)
     ├── unified-content.ts      # Universal content management (8 tools)
     ├── unified-taxonomies.ts   # Universal taxonomy management (8 tools)
     ├── media.ts               # Media management (~5 tools)
@@ -217,6 +287,7 @@ src/
 
 ### Key Features
 
+- **Multi-Site Support**: Manage multiple WordPress sites from a single MCP server instance
 - **Smart URL Resolution**: Automatically detect content types from URLs and find corresponding content
 - **Universal Content Management**: Single set of tools handles posts, pages, and custom post types
 - **Universal Taxonomy Management**: Single set of tools handles categories, tags, and custom taxonomies

diff --git a/claude_desktop_config.json.example b/claude_desktop_config.json.example
@@ -4,9 +4,24 @@
       "command": "npx",
       "args": ["-y", "@instawp/mcp-wp"],
       "env": {
+        "_comment_single_site": "Single site configuration (use this OR multi-site, not both)",
         "WORDPRESS_API_URL": "https://wpsite.instawp.xyz",
         "WORDPRESS_USERNAME": "username",
-        "WORDPRESS_PASSWORD": "Application Password"
+        "WORDPRESS_PASSWORD": "Application Password",
+
+        "_comment_multi_site": "Multi-site configuration (up to 10 sites supported)",
+        "_WORDPRESS_1_URL": "https://production-site.com",
+        "_WORDPRESS_1_USERNAME": "admin",
+        "_WORDPRESS_1_PASSWORD": "app_password_1",
+        "_WORDPRESS_1_ID": "production",
+        "_WORDPRESS_1_DEFAULT": "true",
+        "_WORDPRESS_1_ALIASES": "prod,main",
+
+        "_WORDPRESS_2_URL": "https://staging-site.com",
+        "_WORDPRESS_2_USERNAME": "admin",
+        "_WORDPRESS_2_PASSWORD": "app_password_2",
+        "_WORDPRESS_2_ID": "staging",
+        "_WORDPRESS_2_ALIASES": "stage,dev"
       }
     }
   }