Railway MCP Server

Instructions

Implementation Reference

• src/tools/list-deployments.ts:44-66 (handler)

  The tool's handler function. It calls the listDeployments helper with provided options, handles success/error responses, and returns formatted tool output using createToolResponse.

  handler: async (options: ListDeploymentsOptions) => {
    try {
      const result = await listDeployments(options);
  
      if (!result.success) {
        throw new Error(result.error);
      }
  
      return createToolResponse(result.output);
    } catch (error: unknown) {
      const errorMessage =
        error instanceof Error ? error.message : "Unknown error occurred";
      return createToolResponse(
        "❌ Failed to list Railway deployments\n\n" +
          `**Error:** ${errorMessage}\n\n` +
          "**Next Steps:**\n" +
          "• Ensure you are logged into Railway CLI (`railway login`)\n" +
          "• Check that you have a project linked (`railway link`)\n" +
          "• Verify you have permissions to view deployments\n" +
          "• Try running `railway login` to refresh your authentication"
      );
    }
  },

• src/tools/list-deployments.ts:11-43 (schema)

  Zod input schema defining validation and descriptions for tool parameters: workspacePath, service, environment, limit, json.

  inputSchema: {
    workspacePath: z
      .string()
      .describe("The path to the workspace to list deployments from"),
    service: z
      .string()
      .optional()
      .describe(
        "Service name or ID to list deployments for (defaults to linked service)"
      ),
    environment: z
      .string()
      .optional()
      .describe(
        "Environment to list deployments from (defaults to linked environment)"
      ),
    limit: z
      .number()
      .min(1)
      .max(1000)
      .default(20)
      .optional()
      .describe(
        "Maximum number of deployments to show (default: 20, max: 1000)"
      ),
    json: z
      .boolean()
      .default(false)
      .optional()
      .describe(
        "Return deployments as structured JSON data. When true, the output will contain ids, statuses, and other metadata"
      ),
  },

• src/index.ts:21-31 (registration)

  Dynamic registration loop that registers all exported tools (including 'list-deployments') with the MCP server using name, metadata (title, description, inputSchema), and handler.

  Object.values(tools).forEach((tool) => {
  	server.registerTool(
  		tool.name,
  		{
  			title: tool.title,
  			description: tool.description,
  			inputSchema: tool.inputSchema,
  		},
  		tool.handler,
  	);
  });

• src/cli/deployment.ts:97-158 (helper)

  Supporting helper function that constructs and executes the 'railway deployment list' CLI command with input options, checks CLI version support, handles project linking and errors, returning success/output or error.

  export const listDeployments = async ({
    workspacePath,
    service,
    environment,
    limit = 20,
    json = false,
  }: ListDeploymentsOptions): Promise<
    | {
        success: true;
        output: string;
      }
    | {
        success: false;
        error: string;
      }
  > => {
    try {
      await checkRailwayCliStatus();
  
      const featureSupport = await getCliFeatureSupport();
      if (!featureSupport.deployment.list) {
        const version = await getRailwayVersion();
        return {
          success: false,
          error: `Railway CLI version ${
            version || "unknown"
          } does not support 'deployment list' command. Please upgrade to version 4.10.0 or later.`,
        };
      }
  
      const projectResult = await getLinkedProjectInfo({ workspacePath });
      if (!projectResult.success) {
        return {
          success: false,
          error: projectResult.error ?? "Failed to get project info",
        };
      }
  
      let command = "railway deployment list";
  
      if (service) {
        command += ` --service ${service}`;
      }
  
      if (environment) {
        command += ` --environment ${environment}`;
      }
  
      if (limit) {
        command += ` --limit ${limit}`;
      }
  
      if (json) {
        command += " --json";
      }
  
      const { output } = await runRailwayCommand(command, workspacePath);
      return { success: true, output };
    } catch (error: unknown) {
      return analyzeRailwayError(error, `railway deployment list`);
    }
  };