feat(mcp): local mcp server management

bin.ts

@@ -120,24 +120,24 @@
       });
     },
     (argv) => {
       const finalArgs = {
         ...argv,
         ...readEnvironment(),
       } as any;
 
       let resolvedInstallDir: string;
       if (finalArgs.installDir) {
         if (path.isAbsolute(finalArgs.installDir)) {
           resolvedInstallDir = finalArgs.installDir;
         } else {
           resolvedInstallDir = path.join(process.cwd(), finalArgs.installDir);
         }
       } else {
         resolvedInstallDir = process.cwd();
       }
 
       const wizardOptions: WizardOptions = {
         debug: finalArgs.debug ?? false,
         installDir: resolvedInstallDir,
         cloudRegion: finalArgs.region as CloudRegion | undefined,
         default: finalArgs.default ?? false,
@@ -154,23 +154,42 @@
         'add',
         'Install PostHog MCP server to supported clients',
         (yargs) => {
-          return yargs.options({});
+          return yargs.options({
+            local: {
+              default: false,
+              describe:
+                'Add local development MCP server (http://localhost:8787)',
+              type: 'boolean',
+            },
+          });
         },
         (argv) => {
           const options = { ...argv };
           void runMCPInstall(
-            options as unknown as { signup: boolean; region?: CloudRegion },
+            options as unknown as {
+              signup: boolean;
+              region?: CloudRegion;
+              local?: boolean;
+            },
           );
         },
       )
       .command(
         'remove',
         'Remove PostHog MCP server from supported clients',
         (yargs) => {
-          return yargs.options({});
+          return yargs.options({
+            local: {
+              default: false,
+              describe:
+                'Remove local development MCP server (http://localhost:8787)',
+              type: 'boolean',
+            },
+          });
         },
-        () => {
-          void runMCPRemove();
+        (argv) => {
+          const options = { ...argv };
+          void runMCPRemove(options as { local?: boolean });
         },
       )
       .demandCommand(1, 'You must specify a subcommand (add or remove)')

src/mcp.ts

@@ -13,12 +13,18 @@ import { sleep } from './lib/helper-functions';
 export const runMCPInstall = async (options: {
   signup: boolean;
   region?: CloudRegion;
+  local?: boolean;
 }) => {
-  clack.intro(chalk.bgGreenBright('Installing the PostHog MCP server'));
+  clack.intro(
+    chalk.bgGreenBright(
+      `Installing the PostHog MCP server ${options.local && '(local)'}`,
+    ),
+  );
 
   await addMCPServerToClientsStep({
     cloudRegion: options.region,
     askPermission: false,
+    local: options.local,
   });
 
   clack.log.message(
@@ -36,9 +42,11 @@ export const runMCPInstall = async (options: {
 ${chalk.blueBright(`https://posthog.com/docs/model-context-protocol`)}`);
 };
 
-export const runMCPRemove = async () => {
+export const runMCPRemove = async (options?: { local?: boolean }) => {
   clack.intro(chalk.bgRed('Removing the PostHog MCP server'));
-  const results = await removeMCPServerFromClientsStep({});
+  const results = await removeMCPServerFromClientsStep({
+    local: options?.local,
+  });
 
   if (results.length === 0) {
     clack.outro(`No PostHog MCP servers found to remove.`);

src/steps/add-mcp-server-to-clients/MCPClient.ts

@@ -7,12 +7,13 @@ export abstract class MCPClient {
   name: string;
   abstract getConfigPath(): Promise<string>;
   abstract getServerPropertyName(): string;
-  abstract isServerInstalled(): Promise<boolean>;
+  abstract isServerInstalled(local?: boolean): Promise<boolean>;
   abstract addServer(
     apiKey: string,
     selectedFeatures?: string[],
+    local?: boolean,
   ): Promise<{ success: boolean }>;
-  abstract removeServer(): Promise<{ success: boolean }>;
+  abstract removeServer(local?: boolean): Promise<{ success: boolean }>;
   abstract isClientSupported(): Promise<boolean>;
 }
 
@@ -31,11 +32,12 @@ export abstract class DefaultMCPClient extends MCPClient {
     apiKey: string,
     type: 'sse' | 'streamable-http',
     selectedFeatures?: string[],
+    local?: boolean,
   ) {
-    return getDefaultServerConfig(apiKey, type, selectedFeatures);
+    return getDefaultServerConfig(apiKey, type, selectedFeatures, local);
   }
 
-  async isServerInstalled(): Promise<boolean> {
+  async isServerInstalled(local?: boolean): Promise<boolean> {
     try {
       const configPath = await this.getConfigPath();
 
@@ -46,8 +48,10 @@ export abstract class DefaultMCPClient extends MCPClient {
       const configContent = await fs.promises.readFile(configPath, 'utf8');
       const config = jsonc.parse(configContent) as Record<string, any>;
       const serverPropertyName = this.getServerPropertyName();
+      const serverName = local ? 'posthog-local' : 'posthog';
+
       return (
-        serverPropertyName in config && 'posthog' in config[serverPropertyName]
+        serverPropertyName in config && serverName in config[serverPropertyName]
       );
     } catch {
       return false;
@@ -57,14 +61,16 @@ export abstract class DefaultMCPClient extends MCPClient {
   async addServer(
     apiKey: string,
     selectedFeatures?: string[],
+    local?: boolean,
   ): Promise<{ success: boolean }> {
-    return this._addServerType(apiKey, 'sse', selectedFeatures);
+    return this._addServerType(apiKey, 'sse', selectedFeatures, local);
   }
 
   async _addServerType(
     apiKey: string,
     type: 'sse' | 'streamable-http',
     selectedFeatures?: string[],
+    local?: boolean,
   ): Promise<{ success: boolean }> {
     try {
       const configPath = await this.getConfigPath();
@@ -85,16 +91,18 @@ export abstract class DefaultMCPClient extends MCPClient {
         apiKey,
         type,
         selectedFeatures,
+        local,
       );
       const typedConfig = existingConfig as Record<string, any>;
       if (!typedConfig[serverPropertyName]) {
         typedConfig[serverPropertyName] = {};
       }
-      typedConfig[serverPropertyName].posthog = newServerConfig;
+      const serverName = local ? 'posthog-local' : 'posthog';
+      typedConfig[serverPropertyName][serverName] = newServerConfig;
 
       const edits = jsonc.modify(
         configContent,
-        [serverPropertyName, 'posthog'],
+        [serverPropertyName, serverName],
         newServerConfig,
         {
           formattingOptions: {
@@ -114,7 +122,7 @@ export abstract class DefaultMCPClient extends MCPClient {
     }
   }
 
-  async removeServer(): Promise<{ success: boolean }> {
+  async removeServer(local?: boolean): Promise<{ success: boolean }> {
     try {
       const configPath = await this.getConfigPath();
 
@@ -126,13 +134,15 @@ export abstract class DefaultMCPClient extends MCPClient {
       const config = jsonc.parse(configContent) as Record<string, any>;
       const serverPropertyName = this.getServerPropertyName();
 
+      const serverName = local ? 'posthog-local' : 'posthog';
+
       if (
         serverPropertyName in config &&
-        'posthog' in config[serverPropertyName]
+        serverName in config[serverPropertyName]
       ) {
         const edits = jsonc.modify(
           configContent,
-          [serverPropertyName, 'posthog'],
+          [serverPropertyName, serverName],
           undefined,
           {
             formattingOptions: {

src/steps/add-mcp-server-to-clients/clients/__tests__/claude.test.ts

@@ -328,6 +328,7 @@ describe('ClaudeMCPClient', () => {
         mockApiKey,
         'sse',
         undefined,
+        undefined,
       );
     });
   });

src/steps/add-mcp-server-to-clients/clients/claude-code.ts

@@ -24,14 +24,17 @@ export class ClaudeCodeMCPClient extends DefaultMCPClient {
     }
   }
 
-  isServerInstalled(): Promise<boolean> {
+  isServerInstalled(local?: boolean): Promise<boolean> {
     try {
-      // check if posthog in output
+      // check if specific server name exists in output
       const output = execSync('claude mcp list', {
         stdio: 'pipe',
       });
 
-      if (output.toString().includes('posthog')) {
+      const outputStr = output.toString();
+      const serverName = local ? 'posthog-local' : 'posthog';
+
+      if (outputStr.includes(serverName)) {
         return Promise.resolve(true);
       }
     } catch {
@@ -48,10 +51,17 @@ export class ClaudeCodeMCPClient extends DefaultMCPClient {
   addServer(
     apiKey: string,
     selectedFeatures?: string[],
+    local?: boolean,
   ): Promise<{ success: boolean }> {
-    const config = getDefaultServerConfig(apiKey, 'sse', selectedFeatures);
-
-    const command = `claude mcp add-json posthog -s user '${JSON.stringify(
+    const config = getDefaultServerConfig(
+      apiKey,
+      'sse',
+      selectedFeatures,
+      local,
+    );
+    const serverName = local ? 'posthog-local' : 'posthog';
+
+    const command = `claude mcp add-json ${serverName} -s user '${JSON.stringify(
       config,
     )}'`;
 
@@ -71,8 +81,9 @@ export class ClaudeCodeMCPClient extends DefaultMCPClient {
     return Promise.resolve({ success: true });
   }
 
-  removeServer(): Promise<{ success: boolean }> {
-    const command = `claude mcp remove --scope user posthog`;
+  removeServer(local?: boolean): Promise<{ success: boolean }> {
+    const serverName = local ? 'posthog-local' : 'posthog';
+    const command = `claude mcp remove --scope user ${serverName}`;
 
     try {
       execSync(command);

src/steps/add-mcp-server-to-clients/clients/cursor.ts

@@ -28,7 +28,8 @@ export class CursorMCPClient extends DefaultMCPClient {
   async addServer(
     apiKey: string,
     selectedFeatures?: string[],
+    local?: boolean,
   ): Promise<{ success: boolean }> {
-    return this._addServerType(apiKey, 'sse', selectedFeatures);
+    return this._addServerType(apiKey, 'sse', selectedFeatures, local);
   }
 }

src/steps/add-mcp-server-to-clients/defaults.ts

@@ -68,8 +68,10 @@ export const getDefaultServerConfig = (
   apiKey: string,
   type: MCPServerType,
   selectedFeatures?: string[],
+  local?: boolean,
 ) => {
-  const baseUrl = `https://mcp.posthog.com/${type === 'sse' ? 'sse' : 'mcp'}`;
+  const host = local ? 'localhost:8787' : 'mcp.posthog.com';
+  const baseUrl = `${host}/${type === 'sse' ? 'sse' : 'mcp'}`;
 
   const isAllFeaturesSelected =
     selectedFeatures &&

src/steps/add-mcp-server-to-clients/index.ts

@@ -37,18 +37,21 @@ export const addMCPServerToClientsStep = async ({
   integration,
   cloudRegion,
   askPermission = true,
+  local = false,
 }: {
   integration?: Integration;
   cloudRegion?: CloudRegion;
   askPermission?: boolean;
+  local?: boolean;
 }): Promise<string[]> => {
   const region = cloudRegion ?? (await askForCloudRegion());
 
   const hasPermission = askPermission
     ? await abortIfCancelled(
         clack.select({
-          message:
-            'Would you like to install the MCP server to use PostHog in your editor?',
+          message: local
+            ? 'Would you like to install the local development MCP server?'
+            : 'Would you like to install the MCP server to use PostHog in your editor?',
           options: [
             { value: true, label: 'Yes' },
             { value: false, label: 'No' },
@@ -97,7 +100,7 @@ export const addMCPServerToClientsStep = async ({
     selectedClientNames.includes(client.name),
   );
 
-  const installedClients = await getInstalledClients();
+  const installedClients = await getInstalledClients(local);
 
   if (installedClients.length > 0) {
     clack.log.warn(
@@ -134,14 +137,14 @@ export const addMCPServerToClientsStep = async ({
       return [];
     }
 
-    await removeMCPServer(installedClients);
+    await removeMCPServer(installedClients, local);
     clack.log.info('Removed existing installation.');
   }
 
   const personalApiKey = await getPersonalApiKey({ cloudRegion: region });
 
   await traceStep('adding mcp servers', async () => {
-    await addMCPServer(clients, personalApiKey, selectedFeatures);
+    await addMCPServer(clients, personalApiKey, selectedFeatures, local);
   });
 
   clack.log.success(
@@ -160,10 +163,12 @@ export const addMCPServerToClientsStep = async ({
 
 export const removeMCPServerFromClientsStep = async ({
   integration,
+  local = false,
 }: {
   integration?: Integration;
+  local?: boolean;
 }): Promise<string[]> => {
-  const installedClients = await getInstalledClients();
+  const installedClients = await getInstalledClients(local);
   if (installedClients.length === 0) {
     analytics.capture('wizard interaction', {
       action: 'no mcp servers to remove',
@@ -200,7 +205,7 @@ export const removeMCPServerFromClientsStep = async ({
   }
 
   const results = await traceStep('removing mcp servers', async () => {
-    await removeMCPServer(clientsToRemove);
+    await removeMCPServer(clientsToRemove, local);
     return clientsToRemove.map((c) => c.name);
   });
 
@@ -213,12 +218,14 @@ export const removeMCPServerFromClientsStep = async ({
   return results;
 };
 
-export const getInstalledClients = async (): Promise<MCPClient[]> => {
+export const getInstalledClients = async (
+  local?: boolean,
+): Promise<MCPClient[]> => {
   const clients = await getSupportedClients();
   const installedClients: MCPClient[] = [];
 
   for (const client of clients) {
-    if (await client.isServerInstalled()) {
+    if (await client.isServerInstalled(local)) {
       installedClients.push(client);
     }
   }
@@ -230,14 +237,18 @@ export const addMCPServer = async (
   clients: MCPClient[],
   personalApiKey: string,
   selectedFeatures?: string[],
+  local?: boolean,
 ): Promise<void> => {
   for (const client of clients) {
-    await client.addServer(personalApiKey, selectedFeatures);
+    await client.addServer(personalApiKey, selectedFeatures, local);
   }
 };
 
-export const removeMCPServer = async (clients: MCPClient[]): Promise<void> => {
+export const removeMCPServer = async (
+  clients: MCPClient[],
+  local?: boolean,
+): Promise<void> => {
   for (const client of clients) {
-    await client.removeServer();
+    await client.removeServer(local);
   }
 };